stet_core/

context.rs

// stet - A PostScript Interpreter
// Copyright (c) 2026 Scott Bowman
// SPDX-License-Identifier: Apache-2.0 OR MIT

//! Execution context: stacks, storage, operator table, and state.

use std::io::Write;

use crate::device::OutputDevice;
use crate::dict::DictKey;
use crate::display_list::{DisplayList, GroupParams, SoftMaskParams};
use crate::dual_array_store::DualArrayStore;
use crate::dual_dict_store::DualDictStore;
use crate::dual_string_store::DualStringStore;
use crate::error::PsError;
use crate::file_store::FileStore;
use crate::graphics_state::{GraphicsState, Matrix, PathSegment, PatternData, PsPath};
use crate::name::NameTable;
use crate::object::{EntityId, NameId, ObjFlags, PsObject, PsValue, SaveLevel};
use crate::save_stack::{SaveRecord, SaveStack, StoreType};
use crate::stack::Stack;

/// Operator table entry: function pointer + name.
pub struct OpEntry {
    pub func: fn(&mut Context) -> Result<(), PsError>,
    pub name: NameId,
}

/// Pre-interned `NameId`s for frequently-used names in hot paths.
pub struct NameCache {
    pub n_def: NameId,
    pub n_true: NameId,
    pub n_false: NameId,
    pub n_null: NameId,
    pub n_mark: NameId,
    // Font-related names
    pub n_font_name: NameId,
    pub n_font_type: NameId,
    pub n_font_matrix: NameId,
    pub n_font_bbox: NameId,
    pub n_encoding: NameId,
    pub n_char_strings: NameId,
    pub n_private: NameId,
    pub n_fid: NameId,
    pub n_paint_type: NameId,
    pub n_subrs: NameId,
    pub n_len_iv: NameId,
    pub n_notdef: NameId,
    pub n_metrics: NameId,
    pub n_font_directory: NameId,
    // Resource system names
    pub n_find_resource: NameId,
    pub n_define_resource: NameId,
    pub n_undef_resource: NameId,
    pub n_resource_status: NameId,
    pub n_resource_for_all: NameId,
    pub n_category: NameId,
    pub n_instance_type: NameId,
    pub n_resource_dir: NameId,
    pub n_resource_ext: NameId,
    // Type 3 font names
    pub n_build_char: NameId,
    pub n_build_glyph: NameId,
    // PaintType 2 / WMode support
    pub n_stroke_width: NameId,
    pub n_wmode: NameId,
}

/// Loop state for `for`, `repeat`, `loop`, and `forall`.
pub struct LoopState {
    pub loop_type: LoopType,
    pub proc_entity: EntityId,
    pub proc_start: u32,
    pub proc_len: u32,

    // for/repeat state
    pub counter: f64,
    pub increment: f64,
    pub limit: f64,
    pub use_int: bool,

    // forall state
    pub source: PsObject,
    pub index: u32,
    /// Snapshot of dict keys for dict forall (avoids re-collecting every iteration).
    pub dict_keys: Option<Vec<DictKey>>,

    // pathforall state
    pub path_segments: Option<Vec<PathSegment>>,
    pub path_procs: Option<[PsObject; 4]>, // [move, line, curve, close]
    pub path_ictm: Option<Matrix>,
}

/// Type of loop iteration.
pub enum LoopType {
    For,
    Repeat,
    Loop,
    Forall,
    PathForall,
}

/// Function pointer type for synchronous procedure execution.
/// Set by the engine crate to enable inline PS procedure calls from operators.
pub type ExecSyncFn = fn(&mut Context, PsObject) -> Result<(), PsError>;

/// Key for [`Context::cie_decode_cache`].
///
/// The two leading words are a 128-bit structural fingerprint of the decode
/// procedure (including whatever the dict stack currently binds its
/// executable names to); the remainder is the sample count and the endpoints
/// of the sampled range, as raw bits so the key stays hashable.
pub type CieDecodeKey = (u64, u64, u32, u64, u64);

pub struct Context {
    // Stacks
    pub o_stack: Stack,
    pub e_stack: Stack,
    pub d_stack: Vec<EntityId>,

    // Storage
    pub strings: DualStringStore,
    pub arrays: DualArrayStore,
    pub dicts: DualDictStore,
    pub names: NameTable,
    pub files: FileStore,

    // Loop state storage (indexed by EntityId)
    pub loops: Vec<LoopState>,

    // Operator table
    pub operators: Vec<OpEntry>,

    // Well-known dict IDs
    pub systemdict: EntityId,
    pub globaldict: EntityId,
    pub userdict: EntityId,
    pub errordict: EntityId,
    pub dollar_error: EntityId,

    // State
    pub rand_state: u64,
    /// Last value handed to `srand`, returned by `rrand`. Widened with
    /// [`PsValue::Int`]: `rrand` must return exactly what `srand` was given.
    pub rand_seed: i64,
    /// Current source line number (1-based), updated during scanning.
    pub current_source_line: u32,
    /// Packing mode for array/procedure creation (setpacking/currentpacking).
    pub packing_mode: bool,
    /// Echo mode for %lineedit/%statementedit (PLRM echo operator).
    pub echo: bool,

    // Pre-interned names
    pub name_cache: NameCache,

    // Output: writer for print/= operators (allows capture in tests)
    pub stdout: Box<dyn Write>,

    // VM save/restore
    pub save_stack: SaveStack,
    /// Save stack depth when the current job started (for startjob condition 3).
    pub job_start_save_depth: usize,

    // VM allocation mode: true = global, false = local
    pub vm_alloc_mode: bool,

    /// Binary object format (0-4). Default 0.
    pub object_format: i32,

    // Error dispatch state
    pub current_operator: Option<NameId>,
    /// Whether `nulldevice` was installed at any point during this job.
    ///
    /// Sticky for the job, and deliberately not cleared by a `grestore` that
    /// puts a real device back: it records intent, not current state. A
    /// program that asked for the null device said it wants no output, so
    /// marks it leaves unemitted at end of job are expected rather than a
    /// dropped page worth reporting. The PS test suite is the motivating
    /// case — its files paint into `gsave nulldevice ... grestore` to
    /// exercise operators, never call `showpage`, and must not be nagged
    /// about it.
    pub null_device_used: bool,
    pub in_error_handler: bool,
    /// True during init script execution — relaxes access checks.
    pub initializing: bool,
    /// When true, PS programs can change HWResolution via setpagedevice.
    /// Set by WASM frontend; CLI leaves false to keep DPI under user control.
    pub allow_ps_resolution: bool,

    /// Process exit code requested by the running PS program via the
    /// `.quitwithcode` operator. `None` means "use the default" (0 on
    /// success). The CLI reads this on `PsError::Quit` and propagates
    /// to `std::process::exit`.
    pub exit_code: Option<i32>,

    // Graphics state
    pub gstate: GraphicsState,
    pub gstate_stack: Vec<crate::graphics_state::GstateEntry>,
    /// Storage for gstate objects (PsValue::Gstate indexes into this).
    pub gstate_store: Vec<GraphicsState>,
    pub device: Option<Box<dyn OutputDevice>>,
    pub display_list: DisplayList,
    /// Stack of active transparency-group capture frames. While non-empty,
    /// paint operators emit into the topmost frame's display list instead
    /// of `display_list`. `endtransparencygroup` pops the top frame and
    /// emits a [`stet_graphics::display_list::DisplayElement::Group`] into
    /// the next-innermost target. See `op_begintransparencygroup` /
    /// `op_endtransparencygroup` in `stet-ops::transparency_ops`.
    pub group_stack: Vec<GroupFrame>,
    /// `group_stack.len()` recorded at each `save`. `restore` consults
    /// this to refuse a revert that would unwind across an unbalanced
    /// `begintransparencygroup` / `endtransparencygroup` pair.
    pub save_group_depths: rustc_hash::FxHashMap<u32, usize>,
    /// Registry of OCGs (PDF Optional Content Groups) declared via the
    /// `defineocg` operator. Keyed by the interned `NameId` of the
    /// human-readable layer name from the OCG dict's `/Name` entry.
    /// `beginoptionalcontent` looks up an OCG by name to obtain the
    /// `ocg_id` and `default_visible` it embeds into the emitted
    /// [`stet_graphics::display_list::OcgVisibility::Single`].
    pub ocg_registry: rustc_hash::FxHashMap<NameId, OcgRecord>,
    /// Monotonic counter feeding [`OcgRecord::ocg_id`]. Each call to
    /// `defineocg` increments this; ids never recycle.
    pub next_ocg_id: u32,
    /// Document-level structural data — outline, annotations, metadata,
    /// page boxes, etc. — parallel IR to [`display_list`](Self::display_list).
    /// PostScript `pdfmark` operators populate this; the PDF output device
    /// drains it at end-of-job; non-PDF devices ignore it. Document-global:
    /// `save` / `restore` do not roll this back. See
    /// [`stet_graphics::document_structure`].
    pub doc_structure: stet_graphics::document_structure::DocumentStructure,
    /// When `Some`, each showpage clones the display list here before consuming it.
    /// Used by the WASM frontend to retain display lists for viewport re-rendering.
    /// Each entry is (DisplayList, dpi) where dpi is from the pagedevice HWResolution.
    pub capture_display_lists: Option<Vec<(DisplayList, f64)>>,
    /// When `Some`, each showpage sends a clone of the display list through this channel.
    /// Used by the CLI viewer for incremental display list delivery.
    /// Tuple: `(DisplayList, dpi, page_width, page_height,
    /// effective_cmyk_bytes, cmyk_proofing)`. PostScript pages always pass
    /// `None`/`false` (no PDF/X concept); PDF pages may set these from the
    /// document's OutputIntent context.
    pub display_list_sender: Option<
        std::sync::mpsc::Sender<(
            DisplayList,
            f64,
            u32,
            u32,
            Option<std::sync::Arc<Vec<u8>>>,
            bool,
        )>,
    >,
    pub page_width: u32,
    pub page_height: u32,
    pub output_path: Option<String>,
    /// Page filter: if set, only render pages in this set (1-based).
    pub page_filter: Option<std::collections::HashSet<i32>>,
    /// Factory closure for creating raster devices (registered by CLI).
    #[allow(clippy::type_complexity)]
    pub device_factory: Option<Box<dyn Fn(u32, u32) -> Box<dyn OutputDevice>>>,

    // Font system
    pub font_directory: EntityId,
    pub font_resource_path: Option<String>,
    pub next_fid: i32,

    // Resource system
    pub global_resources: EntityId,
    pub local_resources: EntityId,
    pub category_registry: EntityId,
    pub resource_base_path: Option<String>,

    // Parameter system
    pub user_params: EntityId,
    pub system_params: EntityId,

    /// Backing dict for the `internaldict` operator.
    ///
    /// Created during bootstrap rather than on first use. `Context` holds the
    /// `EntityId` for the whole life of the interpreter, so the dict has to
    /// outlive every `restore`; creating it lazily inside a save bracket would
    /// leave this handle pointing at storage that `restore` reclaims. Entries
    /// written into it after a `save` are still reverted normally, by the
    /// dict's own copy-on-write.
    pub internaldict: EntityId,

    // ICC color profile cache
    pub icc_cache: crate::icc::IccCache,

    // Synchronous procedure execution (set by engine crate)
    pub exec_sync_fn: Option<ExecSyncFn>,

    // Character width set by setcachedevice/setcharwidth during BuildChar execution
    pub char_width: Option<(f64, f64)>,
    // Mode 1 metrics from setcachedevice2: ((w1x, w1y), (vx, vy))
    pub char_width_mode1: Option<((f64, f64), (f64, f64))>,

    // Glyph path cache: per-font charstring interpretation results
    pub glyph_caches: rustc_hash::FxHashMap<EntityId, crate::glyph_cache::GlyphCache>,
    // Type 3 cache mode: set by setcachedevice/setcharwidth during BuildChar
    pub char_cache_mode: Option<crate::glyph_cache::Type3CacheMode>,

    // CID passed from cshow to nested show call for Type 0 composite fonts
    pub cshow_pending_cid: Option<i32>,

    /// Set while a Type 3 glyph procedure runs under `charpath`.
    ///
    /// PLRM: `charpath` "obtains the path for the glyph outlines that would
    /// result if string were shown"; for a Type 3 font that means running the
    /// glyph procedure without painting. While this is `Some`, `fill`,
    /// `eofill` and `stroke` contribute the path they were given here instead
    /// of marking the page — in particular `stroke` contributes the path as
    /// constructed, since `charpath`'s own boolean operand, not the glyph
    /// procedure, decides whether the result gets stroked.
    pub charpath_capture: Option<PsPath>,

    // Pattern/form support
    /// Storage for pattern instances created by `makepattern`.
    pub pattern_store: Vec<PatternData>,
    /// Cache of form display lists keyed by dict EntityId.
    pub form_cache: rustc_hash::FxHashMap<EntityId, DisplayList>,

    /// Memo of sampled CIE decode tables, keyed by a structural fingerprint
    /// of the decode procedure together with the sampled range.
    ///
    /// Sampling one table runs the procedure 256 times, and a CIE colour
    /// space installs up to six of them, so a file that re-installs the same
    /// space per page (what `pdftops` emits for every ICCBased space) pays
    /// thousands of `exec_sync` calls per page. Worse, decode procedures
    /// routinely contain inline array literals, and every evaluation
    /// allocates a fresh array in the non-reclaiming array arena — turning
    /// the repeated sampling into unbounded memory growth.
    ///
    /// Memoising is sound because the PLRM already requires a CIE decode
    /// procedure to be a pure function of its single input: sampling it at
    /// 256 points and interpolating (which this code has always done) is the
    /// same assumption. See `stet_ops::color_ops::eval_decode_table_range`.
    pub cie_decode_cache: rustc_hash::FxHashMap<CieDecodeKey, Vec<f64>>,

    // Timing
    pub start_time: Option<std::time::Instant>,

    // Name resolution cache: invalidated on begin/end/def
    pub dict_version: u64,
    /// Name resolution cache indexed by NameId. Each entry is (dict_version, resolved_object).
    /// Public for inline cache checks in the eval loop's hot path.
    pub name_resolve_cache: Vec<(u64, PsObject)>,

    /// When set, the eval loop aborts with `PsError::Quit` on the next iteration.
    /// Used by the interactive viewer to cancel an in-flight parse when the
    /// user drops a new file.
    pub interrupt_flag: Option<std::sync::Arc<std::sync::atomic::AtomicBool>>,

    /// When true, each successful `showpage` / `copypage` sets `interrupt_flag`
    /// after capturing the display list, so the eval loop yields back to the
    /// caller one page at a time. The caller clears the flag and re-enters
    /// `eval` to drive the next page. Used by the WASM viewer to stream
    /// multi-page PostScript documents: page 1 renders while pages 2..N are
    /// still pending interpretation. Requires `interrupt_flag` to be set.
    pub yield_after_showpage: bool,
}

/// One frame on `Context::group_stack`. Captures paint operators emitted
/// between a `begin*` and a matching close. The active capture target is
/// always [`Self::display_list`]; what happens to it on close depends on
/// [`Self::kind`].
pub struct GroupFrame {
    /// Paint operators emitted while this frame is on top of
    /// `group_stack`. The semantics on close depend on `kind`.
    pub display_list: DisplayList,
    /// What this frame represents — transparency group, soft-mask
    /// builder, or post-`endsoftmask` masked-content scope.
    pub kind: GroupKind,
    /// `gstate.clip_path_version` snapshot taken when the frame opened.
    /// Reserved for future use (e.g. detecting clip changes that
    /// crossed the boundary).
    pub saved_clip_path_version: u32,
    /// `gstate_stack.len()` at the moment the frame opened. Used by
    /// `gsave` / `grestore` and `restore` to refuse pops that would
    /// orphan this frame.
    pub saved_gsave_depth: usize,
}

/// What a [`GroupFrame`] is capturing, determining what gets emitted
/// when it closes.
pub enum GroupKind {
    /// Opened by `begintransparencygroup`. On close, the captured
    /// `display_list` becomes the children of a
    /// `DisplayElement::Group` with these `params`.
    Transparency { params: GroupParams },
    /// Opened by `beginsoftmask`. While active, paint ops emit into the
    /// frame's `display_list` to build the mask form. `endsoftmask`
    /// transmutes the frame to [`Self::Masked`] without popping.
    SoftMask { params: SoftMaskParams },
    /// Implicitly opened by `endsoftmask`. While active, paint ops emit
    /// into `display_list` as the *content* the mask attenuates. On
    /// `clearsoftmask` the frame pops and emits a
    /// `DisplayElement::SoftMasked` carrying `mask`, the captured
    /// content, and `params`.
    Masked {
        mask: DisplayList,
        params: SoftMaskParams,
    },
    /// Opened by `beginoptionalcontent`. On close, the captured
    /// `display_list` becomes the children of a
    /// `DisplayElement::OcgGroup` whose visibility is
    /// `OcgVisibility::Single { ocg_id, default_visible }`.
    OptionalContent { ocg_id: u32, default_visible: bool },
}

/// One entry in `Context::ocg_registry`. `defineocg` allocates these
/// and indexes them by the OCG's interned `NameId` so
/// `beginoptionalcontent` can resolve a name back to its `ocg_id` and
/// the `default_visible` flag the producer set.
#[derive(Clone, Debug)]
pub struct OcgRecord {
    /// Monotonic id assigned by `defineocg`. Embedded into
    /// `OcgVisibility::Single` on the display list.
    pub ocg_id: u32,
    /// Initial visibility, used by the renderer when no `LayerSet`
    /// override exists for this OCG.
    pub default_visible: bool,
}

/// Does `data` contain a complete zlib/deflate stream?
///
/// Used to stop draining a procedure data source that feeds `FlateDecode` and
/// cycles rather than ever returning the empty end-of-data string.
fn is_flate_stream_complete(data: &[u8]) -> bool {
    let mut decomp = flate2::Decompress::new(true);
    let mut out = [0u8; 8192];
    let mut pos = 0;
    loop {
        if pos >= data.len() {
            return false;
        }
        match decomp.decompress(&data[pos..], &mut out, flate2::FlushDecompress::None) {
            Ok(flate2::Status::StreamEnd) => return true,
            Ok(_) => {
                let new_pos = decomp.total_in() as usize;
                if new_pos == pos {
                    return false;
                }
                pos = new_pos;
            }
            Err(_) => return false,
        }
    }
}

impl Context {
    /// Execute a PostScript procedure synchronously and return.
    pub fn exec_sync(&mut self, proc_obj: PsObject) -> Result<(), PsError> {
        let f = self.exec_sync_fn.expect("exec_sync not initialized");
        f(self, proc_obj)
    }

    /// Run any not-yet-executed procedure data source underneath `entity`,
    /// replacing it with the bytes it produces.
    ///
    /// A filter's data source may be a procedure (PLRM 3.8.4), which the
    /// filter is supposed to call for more data as the consumer reads. Running
    /// it when `filter` is *called* instead is observably wrong: the procedure
    /// runs against whatever is on the operand stack at that moment. `pdftops`
    /// builds an inline image as
    ///
    /// ```postscript
    /// << /ImageType 1 ... /DataSource { pdfImStr } /LZWDecode filter >> imagemask
    /// ```
    ///
    /// so `filter` is reached while the enclosing `<< ... >>` is still on the
    /// stack, and `pdfImStr` — which reads its `array index` state off the
    /// stack — would pick up the half-built dictionary instead.
    ///
    /// So the procedure is run here, from the read path, when the consumer's
    /// operands are the ones in place. **Every entry point that reads from a
    /// file must call this first**; see [`FileHandle::PendingProc`].
    ///
    /// The drain is one-shot rather than incremental: the procedure is run to
    /// completion and the result installed as a plain byte source. That keeps
    /// the filters themselves unchanged — none of them has to cope with a
    /// source that is temporarily dry — while still running the procedure at
    /// the right moment, which is what the bug above is about.
    pub fn pump_proc_sources(&mut self, entity: EntityId) -> Result<(), PsError> {
        // A chain can hold more than one procedure source, so loop until the
        // walk reports none left. `pending_proc_source` short-circuits on a
        // counter, so this costs one integer compare on the overwhelmingly
        // common path where no procedure source exists at all.
        while let Some((src, proc, flate_above)) = self.files.pending_proc_source(entity) {
            let data = self.drain_proc_source(proc, flate_above)?;
            self.files.install_proc_data(src, data);
        }
        Ok(())
    }

    /// Call a procedure data source until it signals end of data.
    ///
    /// Per PLRM the procedure pushes a string each call and an empty string
    /// means end of data. `flate_above` additionally stops once the collected
    /// bytes form a complete deflate stream: a procedure feeding `FlateDecode`
    /// may cycle indefinitely rather than ever returning the empty string.
    ///
    /// KNOWN LIMITATION: not every procedure signals end of data at all.
    /// `pdftops` emits paging readers of the form
    ///
    /// ```postscript
    /// { dup 65535 ge { pop 1 add 0 } if 2 index 2 index get 1 index get exch 1 add exch }
    /// ```
    ///
    /// which walk an array of blocks and simply run off the end — they rely on
    /// the *consumer* to stop asking once the image has all its rows, and a
    /// full drain has no such stopping point. Running the procedure truly on
    /// demand, one call per refill, is what those need. That requires
    /// `refill_filter` to be able to re-enter the interpreter, and every
    /// `refill_*` to tell "source temporarily dry" apart from EOF so it does
    /// not latch `eof` on the first short read.
    fn drain_proc_source(
        &mut self,
        procedure: PsObject,
        flate_above: bool,
    ) -> Result<Vec<u8>, PsError> {
        /// Cap on what one procedure data source may produce (64 MB).
        const MAX_PROC_BYTES: usize = 64 * 1024 * 1024;

        let mut data = Vec::new();
        loop {
            let depth_before = self.o_stack.len();
            self.exec_sync(procedure)?;

            if self.o_stack.len() <= depth_before {
                break;
            }
            let result = self.o_stack.peek(0)?;
            match result.value {
                PsValue::String { entity, start, len } => {
                    let bytes = self.strings.get(entity, start, len).to_vec();
                    self.o_stack.pop()?;
                    if bytes.is_empty() {
                        break; // end of data per PLRM
                    }
                    data.extend_from_slice(&bytes);
                    if flate_above && is_flate_stream_complete(&data) {
                        break;
                    }
                    if data.len() >= MAX_PROC_BYTES {
                        break;
                    }
                }
                // Anything other than a string is treated as end of data.
                _ => break,
            }
        }
        Ok(data)
    }

    /// Create a new context with empty stacks and stores.
    /// Call `build_system_dict` afterward to populate operators.
    pub fn new() -> Self {
        let mut names = NameTable::new();

        let name_cache = NameCache {
            n_def: names.intern(b"def"),
            n_true: names.intern(b"true"),
            n_false: names.intern(b"false"),
            n_null: names.intern(b"null"),
            n_mark: names.intern(b"mark"),
            n_font_name: names.intern(b"FontName"),
            n_font_type: names.intern(b"FontType"),
            n_font_matrix: names.intern(b"FontMatrix"),
            n_font_bbox: names.intern(b"FontBBox"),
            n_encoding: names.intern(b"Encoding"),
            n_char_strings: names.intern(b"CharStrings"),
            n_private: names.intern(b"Private"),
            n_fid: names.intern(b"FID"),
            n_paint_type: names.intern(b"PaintType"),
            n_subrs: names.intern(b"Subrs"),
            n_len_iv: names.intern(b"lenIV"),
            n_notdef: names.intern(b".notdef"),
            n_metrics: names.intern(b"Metrics"),
            n_font_directory: names.intern(b"FontDirectory"),
            // Resource system
            n_find_resource: names.intern(b"FindResource"),
            n_define_resource: names.intern(b"DefineResource"),
            n_undef_resource: names.intern(b"UndefineResource"),
            n_resource_status: names.intern(b"ResourceStatus"),
            n_resource_for_all: names.intern(b"ResourceForAll"),
            n_category: names.intern(b"Category"),
            n_instance_type: names.intern(b"InstanceType"),
            n_resource_dir: names.intern(b"ResourceDir"),
            n_resource_ext: names.intern(b"ResourceExtension"),
            n_build_char: names.intern(b"BuildChar"),
            n_build_glyph: names.intern(b"BuildGlyph"),
            n_stroke_width: names.intern(b"StrokeWidth"),
            n_wmode: names.intern(b"WMode"),
        };

        let mut strings = DualStringStore::new();
        let mut dicts = DualDictStore::new();

        // Only systemdict is pre-allocated in Rust — it's needed to register native
        // operators. All other well-known dicts (globaldict, userdict, errordict, $error,
        // FontDirectory) are created by the init scripts in sysdict.ps.
        //
        // `allocate_at_level_zero` is correct here and only here: no `save` can be
        // outstanding during bootstrap, so `save_level = 0` / `created_after_save = 0`
        // is the truth rather than a mis-stamp, and these entities sit below every
        // future save's high-water mark. Everywhere else, use the VM-aware helpers in
        // `stet_ops::vm_ops`.
        let systemdict = dicts.allocate_with(400, b"systemdict", 0, true, 0);
        let globaldict = dicts.allocate_with(100, b"globaldict", 0, true, 0);
        let userdict = dicts.allocate_at_level_zero(200, b"userdict");
        let errordict = dicts.allocate_at_level_zero(50, b"errordict");
        let dollar_error = dicts.allocate_at_level_zero(20, b"$error");
        let font_directory = dicts.allocate_at_level_zero(50, b"FontDirectory");

        // Resource system dicts (global VM)
        let global_resources = dicts.allocate_with(20, b"GlobalResources", 0, true, 0);
        let local_resources = dicts.allocate_at_level_zero(20, b"LocalResources");
        let internaldict = dicts.allocate_at_level_zero(50, b"internaldict");
        let category_registry = dicts.allocate_with(30, b"CategoryRegistry", 0, true, 0);

        // Parameter dicts — pre-populate user_params with recognized keys.
        // setuserparams only updates existing keys; unknown keys are
        // ignored per PLRM.
        let user_params = dicts.allocate_at_level_zero(25, b"UserParams");
        for key_name in [
            "MaxDictStack",
            "MaxExecStack",
            "MaxOpStack",
            "MaxFontItem",
            "MaxFormItem",
            "MaxPatternItem",
            "MaxUPathItem",
            "MaxScreenItem",
            "MaxSuperScreen",
            "MinFontCompress",
            "MaxLocalVM",
            "VMReclaim",
            "VMThreshold",
            "UCacheBLimit",
        ] {
            dicts.put(
                user_params,
                DictKey::Name(names.intern(key_name.as_bytes())),
                PsObject::int(0),
            );
        }
        dicts.put(
            user_params,
            DictKey::Name(names.intern(b"JobName")),
            PsObject::string(strings.allocate_from_at_level_zero(b""), 0),
        );
        dicts.put(
            user_params,
            DictKey::Name(names.intern(b"ExecutionHistory")),
            PsObject::bool(false),
        );
        dicts.put(
            user_params,
            DictKey::Name(names.intern(b"ExecutionHistorySize")),
            PsObject::int(20),
        );
        dicts.put(
            user_params,
            DictKey::Name(names.intern(b"IdiomRecognition")),
            PsObject::bool(true),
        );
        dicts.put(
            user_params,
            DictKey::Name(names.intern(b"AccurateScreens")),
            PsObject::bool(false),
        );
        dicts.put(
            user_params,
            DictKey::Name(names.intern(b"HalftoneMode")),
            PsObject::int(0),
        );

        let system_params = dicts.allocate_at_level_zero(30, b"SystemParams");
        // Cache size limits (PLRM Table C.2 - system parameters)
        for (key, val) in [
            ("MaxFontCache", 67108864),
            ("MaxFormCache", 131072),
            ("MaxPatternCache", 131072),
            ("MaxUPathCache", 131072),
            ("MaxScreenStorage", 524288),
            ("MaxDisplayList", 2097152),
            ("MaxDisplayAndSourceList", 4194304),
            ("MaxSourceList", 2097152),
            ("MaxImageBuffer", 524288),
            ("MaxOutlineCache", 65536),
            ("MaxStoredScreenCache", 0),
            // Read-only current cache usage counters
            ("CurFontCache", 0),
            ("CurFormCache", 0),
            ("CurPatternCache", 0),
            ("CurUPathCache", 0),
            ("CurScreenStorage", 0),
            ("CurSourceList", 0),
            ("CurStoredScreenCache", 0),
            ("CurOutlineCache", 0),
            ("PageCount", 0),
            ("Revision", 1),
        ] {
            dicts.put(
                system_params,
                DictKey::Name(names.intern(key.as_bytes())),
                PsObject::int(val),
            );
        }
        let printer_name = b"stet";
        let printer_str = strings.allocate_from_at_level_zero(printer_name);
        dicts.put(
            system_params,
            DictKey::Name(names.intern(b"PrinterName")),
            PsObject::string(printer_str, printer_name.len() as u32),
        );
        // PLRM: RealFormat names the internal real representation.
        let real_format = b"IEEE";
        let realfmt_str = strings.allocate_from_at_level_zero(real_format);
        dicts.put(
            system_params,
            DictKey::Name(names.intern(b"RealFormat")),
            PsObject::string(realfmt_str, real_format.len() as u32),
        );
        let pw_str = strings.allocate_from_at_level_zero(b"0");
        dicts.put(
            system_params,
            DictKey::Name(names.intern(b"SystemParamsPassword")),
            PsObject::string(pw_str, 1),
        );
        let pw_str2 = strings.allocate_from_at_level_zero(b"0");
        dicts.put(
            system_params,
            DictKey::Name(names.intern(b"StartJobPassword")),
            PsObject::string(pw_str2, 1),
        );
        dicts.put(
            system_params,
            DictKey::Name(names.intern(b"LicenseID")),
            PsObject::int(0),
        );

        // Put self-referencing entries
        let sd_obj = PsObject::dict(systemdict);
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"systemdict")),
            sd_obj,
        );

        let ud_obj = PsObject::dict(userdict);
        dicts.put(systemdict, DictKey::Name(names.intern(b"userdict")), ud_obj);

        let gd_obj = PsObject::dict(globaldict);
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"globaldict")),
            gd_obj,
        );

        let ed_obj = PsObject::dict(errordict);
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"errordict")),
            ed_obj,
        );

        let de_obj = PsObject::dict(dollar_error);
        dicts.put(systemdict, DictKey::Name(names.intern(b"$error")), de_obj);

        let fd_obj = PsObject::dict(font_directory);
        dicts.put(
            systemdict,
            DictKey::Name(name_cache.n_font_directory),
            fd_obj,
        );

        // Register constants in systemdict
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"true")),
            PsObject::bool(true),
        );
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"false")),
            PsObject::bool(false),
        );
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"null")),
            PsObject::null(),
        );

        // mark — literal mark object
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"mark")),
            PsObject::mark(),
        );

        // [ is an alias for mark
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"[")),
            PsObject::mark(),
        );

        // << is a dict mark (distinct from [ mark so ] doesn't match it)
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"<<")),
            PsObject::dict_mark(),
        );

        // version and languagelevel
        dicts.put(
            systemdict,
            DictKey::Name(names.intern(b"languagelevel")),
            PsObject::int(3),
        );

        // Dictionary stack: systemdict, globaldict, userdict
        let d_stack = vec![systemdict, globaldict, userdict];

        Self {
            o_stack: Stack::new(500),
            e_stack: Stack::new(250),
            d_stack,
            strings,
            arrays: DualArrayStore::new(),
            dicts,
            names,
            files: FileStore::new(),
            loops: Vec::new(),
            operators: Vec::new(),
            systemdict,
            globaldict,
            userdict,
            errordict,
            dollar_error,
            rand_state: 0,
            rand_seed: 0,
            current_source_line: 1,
            packing_mode: false,
            echo: false,
            name_cache,
            stdout: Box::new(std::io::stdout()),
            save_stack: SaveStack::new(),
            job_start_save_depth: 0,
            vm_alloc_mode: false,
            object_format: 0,
            current_operator: None,
            null_device_used: false,
            in_error_handler: false,
            initializing: true,
            allow_ps_resolution: false,
            exit_code: None,
            gstate: GraphicsState::new(),
            gstate_stack: Vec::new(),
            gstate_store: Vec::new(),
            device: None,
            display_list: DisplayList::new(),
            group_stack: Vec::new(),
            save_group_depths: rustc_hash::FxHashMap::default(),
            ocg_registry: rustc_hash::FxHashMap::default(),
            next_ocg_id: 0,
            doc_structure: stet_graphics::document_structure::DocumentStructure::new(),
            capture_display_lists: None,
            display_list_sender: None,
            page_width: 612,
            page_height: 792,
            output_path: None,
            page_filter: None,
            device_factory: None,
            font_directory,
            font_resource_path: None,
            next_fid: 0,
            global_resources,
            local_resources,
            category_registry,
            resource_base_path: None,
            user_params,
            system_params,
            internaldict,
            icc_cache: crate::icc::IccCache::new(),
            exec_sync_fn: None,
            char_width: None,
            char_width_mode1: None,
            glyph_caches: rustc_hash::FxHashMap::default(),
            char_cache_mode: None,
            cshow_pending_cid: None,
            charpath_capture: None,
            pattern_store: Vec::new(),
            form_cache: rustc_hash::FxHashMap::default(),
            cie_decode_cache: rustc_hash::FxHashMap::default(),
            #[cfg(not(target_arch = "wasm32"))]
            start_time: Some(std::time::Instant::now()),
            #[cfg(target_arch = "wasm32")]
            start_time: None,
            dict_version: 0,
            name_resolve_cache: Vec::new(),
            interrupt_flag: None,
            yield_after_showpage: false,
        }
    }

    /// Create a context that captures stdout to a buffer (for testing).
    pub fn new_with_output(output: Box<dyn Write>) -> Self {
        let mut ctx = Self::new();
        ctx.stdout = output;
        ctx
    }

    // --- Dictionary stack operations ---

    /// Look up a name in the dictionary stack (top to bottom).
    #[inline]
    pub fn dict_load(&mut self, key: &DictKey) -> Option<PsObject> {
        // Fast path: check name resolution cache
        if let DictKey::Name(name_id) = key {
            let idx = name_id.0 as usize;
            if idx < self.name_resolve_cache.len() {
                let (ver, obj) = self.name_resolve_cache[idx];
                if ver == self.dict_version {
                    return Some(obj);
                }
            }
        }

        // Slow path: search dict stack
        for &dict_id in self.d_stack.iter().rev() {
            if let Some(val) = self.dicts.get(dict_id, key) {
                // Cache the result for Name keys
                if let DictKey::Name(name_id) = key {
                    let idx = name_id.0 as usize;
                    if idx >= self.name_resolve_cache.len() {
                        self.name_resolve_cache
                            .resize(idx + 64, (u64::MAX, PsObject::null()));
                    }
                    self.name_resolve_cache[idx] = (self.dict_version, val);
                }
                return Some(val);
            }
        }
        None
    }

    /// Invalidate the name resolution cache (call on begin/end/def).
    #[inline]
    pub fn invalidate_name_cache(&mut self) {
        self.dict_version = self.dict_version.wrapping_add(1);
    }

    /// Look up and return `(dict_entity, value)` pair.
    pub fn dict_where(&self, key: &DictKey) -> Option<(EntityId, PsObject)> {
        for &dict_id in self.d_stack.iter().rev() {
            if let Some(val) = self.dicts.get(dict_id, key) {
                return Some((dict_id, val));
            }
        }
        None
    }

    /// Store in current dict (top of d_stack).
    pub fn dict_def(&mut self, key: DictKey, value: PsObject) -> Result<(), PsError> {
        let current = *self.d_stack.last().ok_or(PsError::DictStackUnderflow)?;
        self.cow_check_dict(current);
        self.invalidate_name_cache();
        self.dicts.put(current, key, value);
        Ok(())
    }

    /// Store in first dict that contains key, or current dict if not found.
    pub fn dict_store(&mut self, key: DictKey, value: PsObject) -> Result<(), PsError> {
        self.invalidate_name_cache();
        for &dict_id in self.d_stack.iter().rev() {
            if self.dicts.known(dict_id, &key) {
                self.cow_check_dict(dict_id);
                self.dicts.put(dict_id, key, value);
                return Ok(());
            }
        }
        // Not found — store in current dict
        self.dict_def(key, value)
    }

    /// Convert a `PsObject` to a `DictKey`.
    pub fn make_dict_key(&mut self, obj: &PsObject) -> Result<DictKey, PsError> {
        match obj.value {
            PsValue::Name(id) => Ok(DictKey::Name(id)),
            PsValue::Int(v) => Ok(DictKey::Int(v)),
            PsValue::Real(v) => Ok(DictKey::Real(v.to_bits())),
            PsValue::Bool(v) => Ok(DictKey::Bool(v)),
            PsValue::String { entity, start, len } => {
                // Intern string as name — PostScript treats string and name
                // keys as equivalent in dict lookups.
                let bytes = self.strings.get(entity, start, len).to_vec();
                let name_id = self.names.intern(&bytes);
                Ok(DictKey::Name(name_id))
            }
            PsValue::Operator(op) => Ok(DictKey::Operator(op.0)),
            PsValue::Array { entity, start, len } | PsValue::PackedArray { entity, start, len } => {
                Ok(DictKey::Identity(entity.0, start, len))
            }
            PsValue::Dict(entity) => Ok(DictKey::Identity(entity.0, 0, 0)),
            PsValue::Null => Err(PsError::TypeCheck),
            _ => Err(PsError::TypeCheck),
        }
    }

    /// Allocate a new loop state, returning its EntityId.
    pub fn alloc_loop(&mut self, state: LoopState) -> EntityId {
        let id = EntityId(self.loops.len() as u32);
        self.loops.push(state);
        id
    }

    /// Get a loop state by EntityId.
    pub fn get_loop(&self, entity: EntityId) -> &LoopState {
        &self.loops[entity.0 as usize]
    }

    /// Get a mutable loop state by EntityId.
    pub fn get_loop_mut(&mut self, entity: EntityId) -> &mut LoopState {
        &mut self.loops[entity.0 as usize]
    }

    /// Return the display list paint operators should currently append to.
    ///
    /// While a transparency group is active (`group_stack` non-empty),
    /// the topmost frame's display list is returned. Otherwise the
    /// page-level `display_list` is returned. Every paint-emitting
    /// operator must route through this helper to keep group capture
    /// correct.
    #[inline]
    pub fn current_display_list_mut(&mut self) -> &mut DisplayList {
        if let Some(frame) = self.group_stack.last_mut() {
            &mut frame.display_list
        } else {
            &mut self.display_list
        }
    }

    /// Read-only counterpart to [`Self::current_display_list_mut`].
    #[inline]
    pub fn current_display_list(&self) -> &DisplayList {
        if let Some(frame) = self.group_stack.last() {
            &frame.display_list
        } else {
            &self.display_list
        }
    }

    /// Take the display list, optionally capturing a clone for viewport re-rendering.
    ///
    /// This replaces `std::mem::take(&mut ctx.display_list)` at showpage/copypage
    /// call sites. When `capture_display_lists` is active, a clone is saved
    /// along with the current page DPI from the pagedevice HWResolution.
    pub fn take_display_list(&mut self) -> DisplayList {
        if self.capture_display_lists.is_some() {
            let dpi = self.current_page_dpi();
            if let Some(ref mut captures) = self.capture_display_lists {
                captures.push((self.display_list.clone(), dpi));
            }
        }
        if let Some(ref sender) = self.display_list_sender {
            let dpi = self.current_page_dpi();
            // Use the device's actual page size (device pixels), not
            // self.page_width/page_height which are point values.
            let (w, h) = self
                .device
                .as_ref()
                .map(|d| d.page_size())
                .unwrap_or((self.page_width, self.page_height));
            // PS interpreter output: no PDF-specific CMYK profile in play, so
            // the viewer uses its CLI-level default. PDF/X proofing is a
            // PDF-only concept; PostScript always sends `false`.
            let _ = sender.send((self.display_list.clone(), dpi, w, h, None, false));
        }
        // Page-boundary yield: once the display list for this page has been
        // captured (above), signal the eval loop to return so the caller can
        // hand the page off to a renderer before interpreting the next one.
        if self.yield_after_showpage
            && let Some(ref flag) = self.interrupt_flag
        {
            flag.store(true, std::sync::atomic::Ordering::Relaxed);
        }
        std::mem::take(&mut self.display_list)
    }

    /// Read the current page DPI from the pagedevice HWResolution, defaulting to 72.
    pub fn current_page_dpi(&self) -> f64 {
        use crate::dict::DictKey;
        if let Some(pd) = self.gstate.page_device
            && let Some(name_id) = self.names.find(b"HWResolution")
            && let Some(obj) = self.dicts.get(pd, &DictKey::Name(name_id))
            && let PsValue::Array { entity, .. } = obj.value
        {
            let first = self.arrays.get_element(entity, 0);
            return match first.value {
                PsValue::Real(r) => r,
                PsValue::Int(i) => i as f64,
                _ => 72.0,
            };
        }
        72.0
    }

    // --- VM save/restore ---

    /// Perform a `save`: snapshot the current VM state.
    /// Returns a Save PsObject.
    /// Current high-water marks of local VM, for reclamation on restore.
    fn vm_marks(&self) -> crate::save_stack::VmMarks {
        crate::save_stack::VmMarks {
            string_data: self.strings.local.data_len(),
            string_entities: self.strings.local.entities.len(),
            array_data: self.arrays.local.allocated_objects(),
            array_entities: self.arrays.local.entities.len(),
            dict_slots: self.dicts.local.dict_slots(),
            dict_entities: self.dicts.local.entities.len(),
        }
    }

    pub fn vm_save(&mut self) -> PsObject {
        let d_depth = self.d_stack.len();
        let gstate_snapshot = self.gstate.clone();
        let gstate_stack_snapshot = self.gstate_stack.clone();
        let marks = self.vm_marks();
        let (_level, save_id) = self.save_stack.save(crate::save_stack::SaveSnapshot {
            d_stack_depth: d_depth,
            packing_mode: self.packing_mode,
            vm_alloc_mode: self.vm_alloc_mode,
            object_format: self.object_format,
            gstate: gstate_snapshot,
            gstate_stack: gstate_stack_snapshot,
            gstate_store_len: self.gstate_store.len(),
            marks,
        });

        // Implicit gsave: push current gstate marked as save-created (per PLRM).
        // grestoreall stops at this entry; grestore skips it.
        self.gstate_stack.push(crate::graphics_state::GstateEntry {
            state: self.gstate.clone(),
            saved_by_save: true,
        });

        PsObject {
            value: PsValue::Save(SaveLevel(save_id)),
            flags: crate::object::ObjFlags::literal(),
        }
    }

    /// Perform a `restore`: revert VM to the given save state.
    pub fn vm_restore(&mut self, save_id: u32) -> Result<(), PsError> {
        // Validate save_id
        if !self.save_stack.is_valid(save_id) {
            return Err(PsError::InvalidRestore);
        }

        // Per PLRM: "restore can reset VM to the state represented by any
        // save object that is still valid, not necessarily the one produced
        // by the most recent save."  Pop the target level AND all newer
        // levels, undoing COW records from newest to target.
        let levels = self
            .save_stack
            .restore_to(save_id)
            .ok_or(PsError::InvalidRestore)?;

        // Undo COW records from newest level to oldest (reverse order).
        // Each level's records are also processed in reverse.
        // After swapping offsets, reset save_level to 0 so future COW
        // checks at the same save level don't incorrectly skip the backup.
        for level in levels.iter().rev() {
            for record in level.records.iter().rev() {
                match record.store_type {
                    StoreType::String => {
                        self.strings.swap_offsets(record.src, record.copy);
                        self.strings.entity_meta_mut(record.src).save_level = 0;
                    }
                    StoreType::Array => {
                        self.arrays.swap_offsets(record.src, record.copy);
                        self.arrays.entity_meta_mut(record.src).save_level = 0;
                    }
                    StoreType::Dict => {
                        self.dicts.swap_offsets(record.src, record.copy);
                        self.dicts.entity_meta_mut(record.src).save_level = 0;
                    }
                }
            }
        }

        // Restore context parameters from the TARGET save level (first in vec)
        let target = &levels[0];
        self.packing_mode = target.packing_mode;
        self.vm_alloc_mode = target.vm_alloc_mode;
        self.object_format = target.object_format;

        // Restore graphics state from the target level
        self.gstate = target.gstate.clone();
        self.gstate_stack = target.gstate_stack.clone();

        // Reclaim gstate objects created after the save. `check_invalidrestore`
        // has already refused the restore if any of them is still reachable, so
        // truncating here can only drop slots nothing can name.
        self.gstate_store.truncate(target.gstate_store_len);

        // Restore d_stack depth from the target level
        self.d_stack.truncate(target.d_stack_depth);

        // Reclaim everything the restored levels allocated in local VM.
        //
        // Safe by the same PLRM 3.7.3.2 rule `check_invalidrestore` enforces:
        // nothing reachable may still refer to a composite created after the
        // save. The COW swaps above are what make it hold for pre-save objects
        // that were mutated -- `cow_copy` leaves the surviving data at its
        // original offset, below the mark, and parks the discarded mutated copy
        // above it. Global VM is untouched by save/restore, so only local
        // stores are truncated.
        let marks = target.marks;

        // EntityIds become reusable the moment the tables shrink, so anything
        // keyed by one has to be dropped first -- otherwise a future entity
        // reusing the index would hit a stale entry belonging to a dead object.
        // Both caches below are keyed by dict entities.
        let dict_mark = marks.dict_entities;
        let live_dict = |e: &EntityId| e.is_global() || e.raw_index() < dict_mark;
        self.glyph_caches.retain(|entity, _| live_dict(entity));
        self.form_cache.retain(|entity, _| live_dict(entity));

        self.strings
            .local
            .truncate_to(marks.string_data, marks.string_entities);
        self.arrays
            .local
            .truncate_to(marks.array_data, marks.array_entities);
        self.dicts
            .local
            .truncate_to(marks.dict_slots, marks.dict_entities);

        self.invalidate_name_cache();
        self.close_restored_proc_sources();
        self.debug_assert_no_dangling_refs();
        Ok(())
    }

    /// Close any procedure data source whose procedure the restore just
    /// reclaimed.
    ///
    /// `filter` may be handed a procedure and the resulting file read only
    /// later; if a `restore` falls in between, the procedure's array is gone.
    /// PLRM 3.7.3 has `restore` close files opened since the `save`, which is
    /// precisely the right outcome — a subsequent read reports end-of-file
    /// rather than following a retired entity id.
    fn close_restored_proc_sources(&mut self) {
        for (entity, proc) in self.files.pending_proc_handles() {
            if !self.entity_is_live(&proc) {
                self.files.close_pending_proc(entity);
            }
        }
    }

    /// Does `obj`'s composite still exist, or did a `restore` retire it?
    fn entity_is_live(&self, obj: &PsObject) -> bool {
        match obj.value {
            PsValue::Array { entity, .. } | PsValue::PackedArray { entity, .. } => {
                let len = if entity.is_global() {
                    self.arrays.global.entities.len()
                } else {
                    self.arrays.local.entities.len()
                };
                entity.raw_index() < len
            }
            _ => true,
        }
    }

    /// Panic if anything that survived a `restore` names storage the restore
    /// released.
    ///
    /// Reclaiming local VM means retiring entity ids, and an id that outlives
    /// its storage is a use-after-free that surfaces as a panic deep in an
    /// unrelated operator. `check_invalidrestore` is supposed to prevent it by
    /// raising `invalidrestore` first, but it only scans the operand,
    /// execution, and dictionary stacks — the graphics state, `gstate_store`,
    /// and the entity-keyed caches are not covered. This turns the gap from an
    /// argument into something every debug-build test run checks.
    ///
    /// Debug builds only: the sweep is O(size of VM), far too expensive for
    /// release. Run the PS suite or a corpus sweep under a debug build when
    /// touching anything that holds an `EntityId` across a `restore` — the
    /// release build compiles this out entirely.
    #[inline]
    fn debug_assert_no_dangling_refs(&self) {
        #[cfg(debug_assertions)]
        {
            let dangling = crate::vm_audit::audit_dangling_refs(self);
            assert!(
                dangling.is_empty(),
                "restore left {} dangling reference(s):\n  {}",
                dangling.len(),
                dangling
                    .iter()
                    .map(|d| d.to_string())
                    .collect::<Vec<_>>()
                    .join("\n  ")
            );
        }
    }

    // --- COW check methods ---

    /// Check if a string entity needs COW before mutation.
    /// If yes, creates a backup copy and records it.
    pub fn cow_check_string(&mut self, entity: EntityId) {
        let current_level = self.save_stack.current_level();
        if current_level == 0 {
            return; // No save active
        }

        if entity.is_global() {
            return; // Global entities skip local COW
        }
        let meta = self.strings.entity_meta(entity);
        if meta.save_level >= current_level {
            return; // Already copied at this level
        }

        // Perform COW copy
        let copy_id = self.strings.cow_copy(entity);
        self.strings.entity_meta_mut(entity).save_level = current_level;

        self.save_stack.add_record(SaveRecord {
            src: entity,
            copy: copy_id,
            store_type: StoreType::String,
        });
    }

    /// Check if an array entity needs COW before mutation.
    pub fn cow_check_array(&mut self, entity: EntityId) {
        let current_level = self.save_stack.current_level();
        if current_level == 0 {
            return;
        }

        if entity.is_global() {
            return;
        }
        let meta = self.arrays.entity_meta(entity);
        if meta.save_level >= current_level {
            return;
        }

        let copy_id = self.arrays.cow_copy(entity);
        self.arrays.entity_meta_mut(entity).save_level = current_level;

        self.save_stack.add_record(SaveRecord {
            src: entity,
            copy: copy_id,
            store_type: StoreType::Array,
        });
    }

    /// Check if a dict entity needs COW before mutation.
    /// Store into a dictionary, copy-on-writing it first.
    ///
    /// Prefer this over a bare `ctx.dicts.put` for any write into a dictionary
    /// the current operation did not itself allocate — `FontDirectory`, the
    /// resource dictionaries, `userdict`, a caller-supplied dict. Writing
    /// straight through bypasses save/restore: if the dictionary predates the
    /// current `save`, no backup is taken and `restore` will not revert the
    /// entry. That leaves the dictionary holding a value the restore released.
    ///
    /// [`cow_check_dict`](Self::cow_check_dict) is cheap and idempotent — it
    /// returns immediately at save level 0, for global entities, and for
    /// dictionaries already copied at this level — so there is no reason to
    /// skip it when in doubt.
    pub fn dict_put_cow(&mut self, entity: EntityId, key: DictKey, value: PsObject) {
        self.cow_check_dict(entity);
        self.dicts.put(entity, key, value);
    }

    pub fn cow_check_dict(&mut self, entity: EntityId) {
        let current_level = self.save_stack.current_level();
        if current_level == 0 {
            return;
        }

        if entity.is_global() {
            return;
        }
        let meta = self.dicts.entity_meta(entity);
        if meta.save_level >= current_level {
            return;
        }

        let copy_id = self.dicts.cow_copy(entity);
        self.dicts.entity_meta_mut(entity).save_level = current_level;

        self.save_stack.add_record(SaveRecord {
            src: entity,
            copy: copy_id,
            store_type: StoreType::Dict,
        });
    }

    // --- Token conversion ---

    /// Convert a tokenizer token into a PsObject.
    pub fn token_to_object(&mut self, token: crate::tokenizer::Token) -> Result<PsObject, PsError> {
        use crate::tokenizer::Token;
        match token {
            Token::Int(v) => Ok(PsObject::int(v)),
            Token::Real(v) => Ok(PsObject::real(v)),
            Token::String(bytes) => {
                let save_level = self.save_stack.current_level();
                let global = self.vm_alloc_mode;
                let created = self.save_stack.last_save_id();
                let entity = self
                    .strings
                    .allocate_with(bytes.len(), save_level, global, created);
                self.strings
                    .get_mut(entity, 0, bytes.len() as u32)
                    .copy_from_slice(&bytes);
                let mut obj = PsObject::string(entity, bytes.len() as u32);
                if global {
                    obj.flags = ObjFlags::new(ObjFlags::ACCESS_UNLIMITED, false, true, true);
                }
                Ok(obj)
            }
            Token::Name(bytes, is_exec) => {
                let id = self.names.intern(&bytes);
                if is_exec {
                    Ok(PsObject::name_exec(id))
                } else {
                    Ok(PsObject::name_lit(id))
                }
            }
            Token::LiteralName(bytes) => {
                let id = self.names.intern(&bytes);
                Ok(PsObject::name_lit(id))
            }
            Token::ImmediateName(bytes) => {
                let id = self.names.intern(&bytes);
                let key = DictKey::Name(id);
                self.dict_load(&key).ok_or(PsError::Undefined)
            }
            Token::ArrayBegin => {
                let id = self.names.intern(b"[");
                Ok(PsObject::name_exec(id))
            }
            Token::ArrayEnd => {
                let id = self.names.intern(b"]");
                Ok(PsObject::name_exec(id))
            }
            Token::DictBegin => {
                let id = self.names.intern(b"<<");
                Ok(PsObject::name_exec(id))
            }
            Token::DictEnd => {
                let id = self.names.intern(b">>");
                Ok(PsObject::name_exec(id))
            }
            Token::ProcBegin | Token::ProcEnd | Token::Eof | Token::BinaryTokenByte(_) => {
                Err(PsError::SyntaxError)
            }
        }
    }

    /// Reset local VM stores (for job boundary cleanup).
    /// Full implementation deferred until job server loop is built.
    pub fn reset_local_vm(&mut self) {
        self.strings.reset_local();
        self.arrays.reset_local();
        self.dicts.reset_local();
    }
}

impl Default for Context {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_context_creation() {
        let ctx = Context::new();
        assert!(ctx.o_stack.is_empty());
        assert!(ctx.e_stack.is_empty());
        assert_eq!(ctx.d_stack.len(), 3); // systemdict, globaldict, userdict
    }

    #[test]
    fn test_dict_def_and_load() {
        let mut ctx = Context::new();
        let key = DictKey::Name(ctx.names.intern(b"foo"));
        ctx.dict_def(key.clone(), PsObject::int(42)).unwrap();

        let val = ctx.dict_load(&key).unwrap();
        assert_eq!(val.as_i32(), Some(42));
    }

    #[test]
    fn test_dict_where() {
        let mut ctx = Context::new();
        let key = DictKey::Name(ctx.names.intern(b"true"));
        let result = ctx.dict_where(&key);
        assert!(result.is_some());
        let (dict_id, val) = result.unwrap();
        assert_eq!(dict_id, ctx.systemdict);
        assert!(matches!(val.value, PsValue::Bool(true)));
    }

    #[test]
    fn test_dict_store_existing() {
        let mut ctx = Context::new();
        let key = DictKey::Name(ctx.names.intern(b"myvar"));

        // Define in userdict
        ctx.dict_def(key.clone(), PsObject::int(1)).unwrap();

        // Store should update the existing entry in userdict
        ctx.dict_store(key.clone(), PsObject::int(2)).unwrap();

        let val = ctx.dict_load(&key).unwrap();
        assert_eq!(val.as_i32(), Some(2));
    }

    #[test]
    fn test_save_restore_basic() {
        let mut ctx = Context::new();
        let key = DictKey::Name(ctx.names.intern(b"testvar"));

        // Define before save
        ctx.dict_def(key.clone(), PsObject::int(1)).unwrap();

        // Save
        let save_obj = ctx.vm_save();
        let save_id = match save_obj.value {
            PsValue::Save(SaveLevel(id)) => id,
            _ => panic!("Expected Save"),
        };

        // Modify after save
        ctx.dict_def(key.clone(), PsObject::int(2)).unwrap();
        assert_eq!(ctx.dict_load(&key).unwrap().as_i32(), Some(2));

        // Restore
        ctx.vm_restore(save_id).unwrap();
        assert_eq!(ctx.dict_load(&key).unwrap().as_i32(), Some(1));
    }

    #[test]
    fn test_save_restore_string() {
        let mut ctx = Context::new();

        let entity = ctx.strings.allocate_from_at_level_zero(b"hello");

        // Save
        let save_obj = ctx.vm_save();
        let save_id = match save_obj.value {
            PsValue::Save(SaveLevel(id)) => id,
            _ => panic!("Expected Save"),
        };

        // Modify after save
        ctx.cow_check_string(entity);
        ctx.strings.put_byte(entity, 0, b'H');
        assert_eq!(ctx.strings.get(entity, 0, 5), b"Hello");

        // Restore
        ctx.vm_restore(save_id).unwrap();
        assert_eq!(ctx.strings.get(entity, 0, 5), b"hello");
    }

    #[test]
    fn test_save_restore_array() {
        let mut ctx = Context::new();

        let items = [PsObject::int(1), PsObject::int(2), PsObject::int(3)];
        let entity = ctx.arrays.allocate_from_at_level_zero(&items);

        let save_obj = ctx.vm_save();
        let save_id = match save_obj.value {
            PsValue::Save(SaveLevel(id)) => id,
            _ => panic!("Expected Save"),
        };

        ctx.cow_check_array(entity);
        ctx.arrays.set_element(entity, 1, PsObject::int(99));
        assert_eq!(ctx.arrays.get_element(entity, 1).as_i32(), Some(99));

        ctx.vm_restore(save_id).unwrap();
        assert_eq!(ctx.arrays.get_element(entity, 1).as_i32(), Some(2));
    }

    #[test]
    fn test_invalid_restore() {
        let mut ctx = Context::new();
        // Restore without save
        assert_eq!(ctx.vm_restore(999), Err(PsError::InvalidRestore));
    }

    /// The debug-build guard has to actually fire, or it is decoration.
    ///
    /// Planted in `userdict` rather than in one of the entity-keyed caches:
    /// `userdict` predates the save, so it survives the restore, and writing
    /// to it without copy-on-write leaves the reference behind with no backup
    /// to revert. That is the shape of the bug class fixed in 04ddc25, and it
    /// is a path no amount of cache purging can cover.
    #[test]
    #[cfg(debug_assertions)]
    #[should_panic(expected = "dangling reference")]
    fn vm_restore_rejects_a_dangling_reference() {
        let mut ctx = Context::new();
        let save_obj = ctx.vm_save();
        let save_id = match save_obj.value {
            PsValue::Save(SaveLevel(id)) => id,
            _ => panic!("Expected Save"),
        };
        let retired = EntityId(ctx.dicts.local.entities.len() as u32);
        let key = DictKey::Name(ctx.names.intern(b"stale"));
        ctx.dicts.put(ctx.userdict, key, PsObject::dict(retired));
        let _ = ctx.vm_restore(save_id);
    }

    /// `gstate` objects index `gstate_store`, which `restore` now rewinds to
    /// its length at save time.
    #[test]
    fn restore_rewinds_gstate_store() {
        let mut ctx = Context::new();
        ctx.gstate_store.push(ctx.gstate.clone());
        let save_obj = ctx.vm_save();
        let save_id = match save_obj.value {
            PsValue::Save(SaveLevel(id)) => id,
            _ => panic!("Expected Save"),
        };
        ctx.gstate_store.push(ctx.gstate.clone());
        assert_eq!(ctx.gstate_store.len(), 2);
        ctx.vm_restore(save_id).unwrap();
        assert_eq!(ctx.gstate_store.len(), 1);
    }
}