@vibecook/ice 0.11.0 → 0.15.0-desk.1

package/dist/types/packages/core/src/systems/nav-flight.d.ts

@@ -24,7 +24,7 @@
  *   `frozen` ride the resource for T2's departing-plane reflector; T1's camera
  *   math only needs c0/c1.
  */
-import type { TickSystem, World } from "@vibecook/strata-ecs";
+import type { Entity, TickSystem, World } from "@vibecook/strata-ecs";
 import type { CameraState, PortalAffine } from "../../../kernel/src/index";
 /** The one in-flight nav transition (design-006 §3.1). Inactive = at rest. */
 export declare const NavTransition: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
@@ -37,8 +37,29 @@ export declare const NavTransition: import("@vibecook/strata-ecs").Resource<impo
     readonly frozen: import("@vibecook/strata-ecs").FieldSpec<"bool", true>;
     /** Bumps on every flight start; T2 distinguishes retarget from resume. */
     readonly epoch: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    /** CanvasSession/document identity captured at the authority cut. */
+    readonly documentEpoch: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    readonly fromFrame: import("@vibecook/strata-ecs").FieldSpec<"eid", true>;
+    readonly toFrame: import("@vibecook/strata-ecs").FieldSpec<"eid", true>;
+    readonly fromTypeId: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly toTypeId: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
     /** Response multiplier from octave distance (locked at start; §4). */
     readonly durMul: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    /**
+     * The DEPARTED frame's camera at the cut (design-013 §8 B7, D-B7.1): what it renders under
+     * at p = 0 — bit for bit, never through the affine and back — and throughout a frozen
+     * flight. `departedCameraOf` is the one reader.
+     */
+    readonly fromX: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly fromY: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly fromZ: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    /**
+     * Ticks the spring has stepped. The FIRST tick after the cut holds at p = 0 (B7): one frame
+     * is drawn with the camera at the exact `c0` — the arriving frame IS the portal's last frame,
+     * the departed frame IS its pre-cut frame — so the cut changes no pixel and the motion begins
+     * from a frame that exists. The oracle's `p = 0` still is a product frame, not a fiction.
+     */
+    readonly ticks: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
     readonly c0x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
     readonly c0y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
     readonly c0z: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
@@ -59,8 +80,29 @@ export declare const NavTransition: import("@vibecook/strata-ecs").Resource<impo
     readonly frozen: import("@vibecook/strata-ecs").FieldSpec<"bool", true>;
     /** Bumps on every flight start; T2 distinguishes retarget from resume. */
     readonly epoch: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    /** CanvasSession/document identity captured at the authority cut. */
+    readonly documentEpoch: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    readonly fromFrame: import("@vibecook/strata-ecs").FieldSpec<"eid", true>;
+    readonly toFrame: import("@vibecook/strata-ecs").FieldSpec<"eid", true>;
+    readonly fromTypeId: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly toTypeId: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
     /** Response multiplier from octave distance (locked at start; §4). */
     readonly durMul: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    /**
+     * The DEPARTED frame's camera at the cut (design-013 §8 B7, D-B7.1): what it renders under
+     * at p = 0 — bit for bit, never through the affine and back — and throughout a frozen
+     * flight. `departedCameraOf` is the one reader.
+     */
+    readonly fromX: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly fromY: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly fromZ: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    /**
+     * Ticks the spring has stepped. The FIRST tick after the cut holds at p = 0 (B7): one frame
+     * is drawn with the camera at the exact `c0` — the arriving frame IS the portal's last frame,
+     * the departed frame IS its pre-cut frame — so the cut changes no pixel and the motion begins
+     * from a frame that exists. The oracle's `p = 0` still is a product frame, not a fiction.
+     */
+    readonly ticks: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
     readonly c0x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
     readonly c0y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
     readonly c0z: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
@@ -72,14 +114,54 @@ export declare const NavTransition: import("@vibecook/strata-ecs").Resource<impo
     readonly aox: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
     readonly aoy: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
 }>;
+export interface NavTransitionIdentity {
+    readonly documentEpoch: number;
+    readonly fromFrame: Entity;
+    readonly toFrame: Entity;
+    readonly fromTypeId: string;
+    readonly toTypeId: string;
+}
+/** The one in-flight transition's field values, as `departedCameraOf` reads them. */
+export interface DepartedCameraInputs {
+    readonly frozen: boolean;
+    readonly c0x: number;
+    readonly c0y: number;
+    readonly c0z: number;
+    readonly fromX: number;
+    readonly fromY: number;
+    readonly fromZ: number;
+    readonly as: number;
+    readonly aox: number;
+    readonly aoy: number;
+}
+/**
+ * The camera the DEPARTED frame renders under this frame (design-013 §8 B7, D-B7.1; the
+ * ground's `departedCamera`, moved onto the resource). Riding the flight through the affine
+ * (`outgoingCamera`) — except at the cut itself, where it is the pre-cut camera bit for bit
+ * (the affine and its inverse round-trip to within an ulp, and at zoom 1 an ulp is the other
+ * side of a decade), and throughout a FROZEN flight, where the departed frame stays at its
+ * pre-cut appearance and fades (design-006 §5: the cap broke the geometry, so the story is a
+ * dissolve, not a portal). Every presenter of the departed frame — the ground's second slot,
+ * the DOM's departing plane — reads this one rule, so they agree to the bit.
+ */
+export declare function departedCameraOf(t: DepartedCameraInputs, cam: CameraState): CameraState;
 /**
  * Arm a flight from the already-cut world: continuity-solve was done by the
- * caller (`exact` = c0 in destination-frame coords), the arrival `c1` is
+ * caller (`exact` = c0 in destination-frame coords — from a LIVE PORTAL the
+ * camera the inside was already rendering under, `outgoingCamera(M, camPre)`,
+ * so the cut changes no pixel; D-B7.1), the arrival `c1` is
  * already clamped. Applies the depth cap (§5), snaps the camera to c0, and
  * activates the resource. Callers guarantee a live Viewport — headless/no-
  * viewport paths snap to the arrival instead and never reach here.
  */
-export declare function startNavFlight(world: World, kind: "enter" | "exit", A: PortalAffine, exact: CameraState, c1: CameraState): void;
+export declare function startNavFlight(world: World, kind: "enter" | "exit", A: PortalAffine, exact: CameraState, c1: CameraState, identity?: NavTransitionIdentity): void;
+/**
+ * Publish an epoch-bound logical switch even when geometry is deliberately cut. A cut that
+ * lands mid-flight ENDS that flight: its departed set is released here, because the tick that
+ * owns the release never runs for an inactive resource (B9 review blocker 4 — `Retained` leaked
+ * for the session, and Residency never evicted those keys).
+ */
+export declare function publishNavCut(world: World, kind: "enter" | "exit", from: CameraState, to: CameraState, identity?: NavTransitionIdentity, A?: PortalAffine): void;
 /** Deactivate without touching the camera (integrity pops, gesture yields). */
 export declare function abortNavFlight(world: World): void;
 /**

package/dist/types/packages/core/src/systems/nav-tap.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The ENTER GESTURE (design-015 §9; D2b) — a double-tap on a `Container` asks to enter it, a
+ * double-tap on the bare frame asks to leave. `ctl:behave`, after `selectBehavior`: the first
+ * tap SELECTS at once (the prototype's click), the second — the same target, within
+ * `multiTapWindowMs`, within `multiTapSlopPx` — is the gesture. Detected from two INSTANT
+ * taps (each Recognized at count 1) held in `NavTapMemo`, not from a `MultiTap(2)` opt-in on
+ * the target: that machinery parks the first tap Pending for the whole window, so a plain
+ * click on a container would select 280 ms late — a latency the prototype never had (its
+ * first click selected, its dblclick entered). `MultiTap` stays what it is for widgets that
+ * want a counted tap.
+ *
+ * The op itself is NOT run here: `enterContainer` spawns, writes tags and rebuilds the index —
+ * structural writes, illegal mid-tick. The gesture writes the one-tick `NavIntent` fact and the
+ * facade applies it once `engine.step` returns (nav-geometry.ts). A tap on a PART (`DownPart`)
+ * is the app's and never counts; a tap while a flight drives is not a double-tap's first half
+ * (the flight yields to nothing but a camera gesture).
+ */
+import type { Entity, System, World } from "@vibecook/strata-ecs";
+/** The last instant tap: its target (0 = the bare frame), where and when — the double-tap's first half. */
+export declare const NavTapMemo: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly target: import("@vibecook/strata-ecs").FieldSpec<"eid", true>;
+    readonly x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly at: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    /** Bumps per tap seen; 0 = no memo. */
+    readonly seq: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+}>, {
+    readonly target: import("@vibecook/strata-ecs").FieldSpec<"eid", true>;
+    readonly x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly at: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    /** Bumps per tap seen; 0 = no memo. */
+    readonly seq: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+}>;
+export interface NavTapOpts {
+    /** Is this entity a container the engine may enter (the facade's catalog-backed test)? Default: the `Container` tag. */
+    readonly isContainer?: (entity: Entity) => boolean;
+    /**
+     * Is this entity an object that OPENS (design-015 §8, D4b — the facade's catalog-backed test: its widget type
+     * declares `openable`)? A double-tap on one asks to pick it up (`HeldIntent`), not to enter it. Default: nothing opens.
+     */
+    readonly isOpenable?: (entity: Entity) => boolean;
+}
+export declare function createNavTap(world: World, opts?: NavTapOpts): System;

package/dist/types/packages/core/src/systems/press-button.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The button a press began with (petition I28) — read off the pointer's `PointerButtons.buttons` on its `WentDown` tick, which is
+ * the down fact's own PointerEvent `buttons` mask (ingest's fold ends at the transition, l0-input.ts). A pointerdown carries the
+ * one button that pressed: a second button joining a held press arrives as a pointermove (the Pointer Events spec's chorded
+ * buttons), never as a down.
+ *
+ *   - PRIMARY — bit 1 (a mouse's left button, a touch, a pen's tip) or 32 (a pen's eraser end: the board's eraser reads it), or
+ *     no bit at all (a synthetic down that names no button — every press, as before I28). The recognizers take it, and the hand.
+ *   - MIDDLE — bit 4: a drag only where its drag pans — `dragRoute`'s device convention on the bare canvas (design-003 §4.4), the
+ *     hand's pan brought close (held.ts) — and never a tap, a long press, or a grab of what is under it.
+ *   - SECONDARY — anything else (2: the right button, a pen's barrel; 8/16: back and forward): a POINT. Its point, its pick and
+ *     its hover move with it (ingest, `picking`); nothing selects, drags, enters or works a part. Its `contextmenu` is the host's.
+ *
+ * Pure over the ctx: no writes.
+ */
+import type { Entity, SystemCtx } from "@vibecook/strata-ecs";
+export type PressButton = "primary" | "middle" | "secondary";
+/** The button a press began with, from the `buttons` mask its down carried. */
+export declare function pressButton(buttons: number): PressButton;
+/**
+ * Whether a MIDDLE press on `captured` is a drag: where `dragRoute` sends a drag to its CANVAS branch, whose device convention pans
+ * — the bare canvas, or a capture that is no handle, no port and no object (a wire). Over a handle, a port or an object it is a
+ * point: before I28 it resized, connected or MOVED what it landed on.
+ */
+export declare function middlePans(ctx: Pick<SystemCtx, "has" | "hasTag">, captured: Entity | undefined): boolean;

package/dist/types/packages/core/src/systems/press-wheel.d.ts

@@ -0,0 +1,11 @@
+/**
+ * THE WHEEL OF A HOLDING PRESS (design-015 §6's photo; D3t-a — PHOTO.md: "wheel while holding turns the print about the
+ * finger"). While a local pointer's press holds a widget that declares `interaction.wheelTurns` (its `WheelTurns`
+ * capability — a recognizer of the press captures it), the wheel on that pointer is the WIDGET's: this system stamps the
+ * one-tick `WheelHandled` (both wheel consumers skip it — the camera never zooms under a carried print) and adds the tick's
+ * deltas to the pointer's `PressWheel`, a running sum a reflector can still read after the tick, when `PointerWheel` has been
+ * zeroed. The sum starts at the press's first wheel and leaves with the press. The head of `react`, beside the held input:
+ * the ingest's facts are flushed by then and what this stamps flushes before `ctl`.
+ */
+import type { System, World } from "@vibecook/strata-ecs";
+export declare function createPressWheel(world: World): System;

package/dist/types/packages/core/src/systems/tray.d.ts

@@ -0,0 +1,111 @@
+/**
+ * TRAY INPUT (design-016 §7; design-017 §4 — K3) — the pegboard drawer's share of the pointer, beside the hand's (systems/held.ts)
+ * and in its vocabulary. Right after `heldInput` at the head of `react`: the ingest's one-tick tags are flushed by then (a press is
+ * visible), and what this stamps flushes before `ctl`, so the recognizers and both wheel consumers never hear of what the tray
+ * takes. PICKING does not hear it either way — it runs in this same phase, before the stamp lands (a tag is a structural write,
+ * applied at the phase boundary) — so it reads `Tray.open` itself and answers the bare canvas for every local pointer while the
+ * drawer is out (l1-pick; K9 law #1: without that, the DOM-at-event-time halves read a live hit THROUGH the drawer). While an
+ * object is in hand the tray stands aside (the hand's frame never draws it).
+ *
+ *  - CLOSED, the drawer takes no pointer (design-018 §5, R2 — the lip's handle, its hover and its press retired): a press at the
+ *    bottom centre is the desk's like any other. What opens the drawer is the app's — the `a` key, and the DOM bar (`<TrayBar>`,
+ *    @ice/react), whose down never reaches the canvas as a press. Only a wheel stream it took while out stays its own (below).
+ *  - OPEN, the desk is INERT: every local pointer gets the one-tick `HandledByWidget` and `WheelHandled`, each tick, as the hand's
+ *    do — so "the wheel never moves the camera" is not a rule the camera keeps; it is a fact the camera never hears about. Over the
+ *    drawer the wheel scrolls it (`dy`; the OS's momentum arrives as deltas and is applied as it comes — no inertia of ours; ⌘/ctrl
+ *    and a pinch are swallowed) and a press-drag scrolls it; past an end the rest is the band's `stretch` (a reversal unwinds it
+ *    first), which lets go once the scroll input has been quiet `letGoMs` — or (K9) once a FADING tail has pushed it `fadeDeltas`
+ *    shrinking deltas, the rest of that tail spent (the OS's momentum no longer holds it for its second). A click on the dimmed desk — pressed and released there,
+ *    unmoved — closes it. Shut, the wheel stays the tray's until it has been quiet `letGoMs` (K9): a flick's momentum still
+ *    arriving as the drawer shuts never zooms the desk.
+ *  - K5b, TAKING ONE (design-017 §9): a press on a SPECIMEN is `TrayPress specimen` — its type, the grab point across the object as the
+ *    board draws it (kernel `specimenFit`), the specimen's centre on screen. Past the slop its COPY lifts (`Tray.take` and the pointer:
+ *    the renderer's flux draws it; the specimen stays hung); a press on a specimen never scrolls the board. Out of the drawer's open
+ *    rect the copy is HANDED to the desk: the drawer slides away (`open` false), `handed` bumps (that tick `take` still names it, where
+ *    it left — what the renderer's ghost grows out of — and it clears the tick after), and the one-tick `TrayIntent` asks the
+ *    facade for `ops.insertByDrag` after the step — the insert ghost under the same grab point, its synthetic down this pointer's, the
+ *    ordinary drag from there. The press becomes `carry`: released back over the drawer as drawn — still sliding away, its open rect
+ *    the desk's once it has shut (K9) — the ghost's gesture is CANCELLED
+ *    (`CancelRequest` — the ctl sweep reads it this tick, before the release can commit) and it flies home. Released inside the drawer,
+ *    or the drawer shut under it (Esc, the key), the take is put back: nothing was made, nothing enters undo.
+ *
+ * Where the drawer is comes through the SEAM `TrayPoseSlot` beside `heldPose`: the renderer's word on the drawer as it DREW it this
+ * frame (its rect mid-slide, the scroll range its layout gives), so a hit and the clamp agree with the pixels. Nothing here reads a
+ * kind or a pixel; opening a drawer cancels every gesture in flight (`CancelRequest`, read by the `ctl:spawn` sweep this tick).
+ */
+import type { Entity, System, TickSystem, World } from "@vibecook/strata-ecs";
+import type { DropPlacementPolicy } from "./l3-drop";
+import { type WidgetType } from "../widget/define-widget";
+/**
+ * The drawer ON SCREEN as the renderer drew it this frame, CSS px: its outline box (top-left, width, full height — the part below
+ * the view included), the slide `p` (0 closed … 1 open), the scroll range `max` the laid content gives, the board's `pitch`, and
+ * the `scroll` as DRAWN — the fact's plus the band's shown pull — so a board point under the pointer is the one on screen. K9: the
+ * `face`, the board's height the drawer shows inside its rim — the range is the content's foot plus a pitch less it (kernel
+ * `trayScrollMax`), so the lay can clamp the scroll in the tick a new foot or face moves the range; absent, nothing clamps it.
+ * design-018 R4: the `head`, how far under its top nothing of the board's content shows (the renderer's clear HEADER, where a host lays
+ * the category chips) — a specimen scrolled under it is never hovered or taken there: a press there is the board's; absent, 0.
+ * Petition I21: the `foot`, how far above its bottom edge nothing of the content shows (a host's foot inset — its line floats over the
+ * board there): the same at the foot, and the range is the content's foot plus a pitch less the face ABOVE it; absent, 0.
+ */
+export interface TrayScreenFrame {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly p: number;
+    readonly max: number;
+    readonly pitch: number;
+    readonly scroll: number;
+    readonly face?: number;
+    readonly head?: number;
+    readonly foot?: number;
+}
+/** The pose seam: the renderer's word on where the drawer is — `undefined` before its first frame. */
+export interface TrayPoseSource {
+    frame(): TrayScreenFrame | undefined;
+}
+/** The stack's slot for the pose source — a mutable box, so the renderer can arrive after install (as `heldPose`). */
+export interface TrayPoseSlot {
+    current: TrayPoseSource | null;
+}
+/** The tray's input numbers (design-017 §7): a click's slop, how long the scroll input must be quiet before the band lets go — and (K9, D-K9-c.3) how many shrinking deltas in a row a fading tail pushes the band before it lets go. (design-018 §5: the lip's drag, handle and pad retired with it.) */
+export declare const TRAY_INPUT: {
+    readonly slopPx: 4;
+    readonly letGoMs: 120;
+    readonly fadeDeltas: 3;
+};
+/** The tray's specimens (K5a): the tray entity's children tagged `Specimen`, in sibling order. */
+export declare function specimensOf(world: World, tray: Entity): Entity[];
+/** A delta down the board into scroll ∈ [0, max], the rest into the band; a delta back unwinds the band first. */
+export declare function scrollBy(scroll: number, stretch: number, d: number, max: number): {
+    readonly scroll: number;
+    readonly stretch: number;
+};
+export declare function createTrayInput(world: World, opts: {
+    readonly pose: TrayPoseSlot;
+}): System;
+/** The catalog's object types that carry a tray entry — the tray's contents (K-L2: no list here names a kind); the registry's in an unbound world. The lay hangs those the current frame takes (K9). */
+export declare function hungTypes(world: World): WidgetType[];
+/**
+ * THE TRAY'S LAY (design-017 §8; K5a) — the specimens in the world: one RUNTIME entity per object type whose widget carries a tray
+ * entry (`hungTypes`), `ChildOf` the tray entity (the root of its runtime canvas), `PrefabId` its type, `Position`/`Size` where the
+ * lattice law lays it (kernel `layTray`) across the drawer AS THE RENDERER DREW IT (the pose seam's width and pitch), its entry's
+ * props over the widget's defaults, spawned `Specimen` and already `WidgetEquipped` (nothing stamps it; the spatial index never
+ * takes it). Laid once the renderer has said how wide the drawer is; re-laid when that width, the pitch or the entries change (a
+ * kind registered), a specimen whose kind left destroyed; after a reset the new tray entity is laid afresh. `TrayContent` records
+ * what was laid — the content's foot is the renderer's scroll range. A tick system: its spawns are the scheduler's, once a frame.
+ * K9 (S10, D-K9-c.2): when that range MOVES — a lay (the width, the kinds) or the drawer's face (the view's height) — a scroll past its
+ * new end with nothing stretching is clamped to it in the same tick, so no frame draws blank board past the content and the next wheel
+ * starts from the end; only on a move, so the rig's door (`scrollTray`) still takes any value until the range next moves.
+ * K9 (S13, D-K9-c.4): it hangs what the CURRENT frame takes — inside an entered container its ingress, at the root its canvas's
+ * placement, the authority a drop's commit asks (`placement`) — so no specimen offers a take the frame would refuse; entering or
+ * leaving re-lays it (the drawer is shut then: the desk is inert while it is out). Without a policy, every hung type.
+ * design-018 §6 (R2) — THE FILTER: of those it lays only the entries of the category the drawer shows (`Tray.category`, "" all); a
+ * change of it re-lays, and the board starts again at its top — the scroll and the band zeroed. A category the frame hangs none of
+ * (its last entry gone with the frame, or an id no entry names) falls back to all. What the frame could hang before the filter — its
+ * categories in the lay's order and their counts — is recorded in `TrayContent.present` (the ops' `trayCategories`: a host's chips).
+ */
+export declare function createTrayLay(world: World, opts: {
+    readonly pose: TrayPoseSlot;
+    readonly placement?: DropPlacementPolicy | undefined;
+}): TickSystem;

package/dist/types/packages/core/src/systems/zoom-through.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The ZOOM-THROUGH (design-015 §9, design-013 Q13 → ON; PORTAL.md §8 — D2b). `ctl:behave`,
+ * after `cameraControl`: on a frame whose wheel zoomed (`WheelZoomStep`, D2a-core's one-tick
+ * fact — pans never cut, and the touch pinch is not recorded there, D-D2a.6), when no flight
+ * drives and the settings say so —
+ *
+ * - a zoom IN: the topmost Active container (paint order) whose face has come in whole
+ *   (presence 1) AND covers the whole viewport by `in` CSS px is entered as a CUT nobody can
+ *   see: the view already IS its inside, and the cut lands on the camera the inside was
+ *   rendering under (`transition: "cut"`).
+ * - a zoom OUT: when the current frame's own face — under the parent camera the inside
+ *   renders as it does now, the continuity solve — no longer covers the view by `out` px, the
+ *   frame is left as a cut onto that parent camera.
+ *
+ * Both are asked through the one-tick `NavIntent` fact (ops are structural — illegal mid-tick;
+ * the facade applies it right after the step) with `redress` set: the entered desk was DRESSED
+ * for its arrival as a face (`from` = the arrival's zoom), the left desk for the camera it was
+ * cut at (`from` = the camera's zoom) — the renderer re-dresses over its own ramp and hands the
+ * lamp over on it (`NavRedress`, written by the applier). The faces come through the nav
+ * geometry seam (the drawn face, the gate's answer, the cover test), else core's static rect.
+ */
+import type { Entity, TickSystem, World } from "@vibecook/strata-ecs";
+import { type NavGeometrySlot } from "../nav/nav-geometry";
+export interface ZoomThroughOpts {
+    /** The nav geometry seam the faces are read through (the interaction stack's slot). */
+    readonly navGeometry?: NavGeometrySlot;
+    /** Is this entity a container the engine may enter (the facade's catalog-backed test)? Default: any `Container`. */
+    readonly isContainer?: (entity: Entity) => boolean;
+}
+export declare function createZoomThrough(world: World, opts?: ZoomThroughOpts): TickSystem;

package/dist/types/packages/core/src/tools/define-tool.d.ts

@@ -8,6 +8,8 @@
  * Built-ins ship as configs of this same primitive:
  *  - select: tap/longPress/drag; canvas drag → marquee (pan on touch /
  *    space / middle-button — device conventions, honored ABOVE tool policy).
+ *    A shift-held canvas drag takes `route.canvasDragShift` (design-015 §9,
+ *    D2a-core), which defaults to the tool's own `canvasDrag`.
  *  - pan: hand cursor; every drag pans.
  *  - connect: crosshair; widget/port drags connect (design-003 §5.8).
  *  - draw(widgetType): factory — canvas drag creates ONE widget from the
@@ -24,6 +26,14 @@ export type WidgetDragRoute = "move" | "pan" | "connect" | "none";
 export interface ToolRoute {
     /** Drag starting on empty canvas (after device overrides: touch/space/middle → pan). */
     readonly canvasDrag?: CanvasDragRoute;
+    /**
+     * The same drag with SHIFT held (design-015 §9, D-D11 — D2a-core): the desk's
+     * select tool pans the bare mat and draws its marquee on shift —
+     * `{ canvasDrag: "pan", canvasDragShift: "marquee" }`. Omitted: the tool's
+     * own `canvasDrag`, so shift changes nothing (every tool before this field).
+     * The device conventions (touch / space / middle → pan) still sit above it.
+     */
+    readonly canvasDragShift?: CanvasDragRoute;
     /** Drag starting on a widget body. */
     readonly widgetDrag?: WidgetDragRoute;
     /** Drag starting on a port entity ("connect" | "none"). */