@storylet-studio/model 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -409,10 +409,30 @@ interface PropertyDecl {
      * the game's own state, always engine-level, never per-flow.
      */
     shared?: boolean;
+    /**
+     * The durability axis (design/engine-server.md 4.2), valid wherever `shared`
+     * is valid and orthogonal to it: `shared` says whose value this is WITHIN a
+     * run, `durable` says whether the value survives the run at all. A durable
+     * shared property is the installation's memory ("trolls defeated since we
+     * opened"); a durable per-flow one is the player's pocket (visits,
+     * allegiance, what they earned).
+     *
+     * INERT TO THE RUNTIME. The engine partitions by `shared` alone and never
+     * reads this. Durability is what the SERVER does at a run boundary: it reads
+     * the declarations, lifts the durable values out of the partitions before the
+     * world restarts, and writes them back into the fresh engine afterwards,
+     * entirely through `getProperty` / `setProperty`.
+     *
+     * On a `@world` declaration the flag is a validation error, for the reason
+     * `shared` is: @world is the game's own state, and how long the game keeps it
+     * is the game's business.
+     */
+    durable?: boolean;
     purpose?: string;
 }
-/** A card-template field (box-defined). Data for the host; the engine never
- *  interprets fields and they are not addressable from expressions. */
+/** A template field (box-defined), of the card template or of the outcome
+ *  fields. Data for the host; the engine never interprets fields and they are
+ *  not addressable from expressions. */
 interface FieldDecl {
     name: string;
     type: PropertyType;
@@ -433,6 +453,32 @@ declare function effectiveGameId(entity: {
     title?: string;
     id: string;
 }): string;
+/** The three answers a value address needs, all derived from the bundle. */
+interface ValueAddresses {
+    /** Tag internal id -> the owner segment an address PRINTS for it. */
+    print: Map<string, string>;
+    /** Every owner segment a value address ACCEPTS -> the tag's internal id.
+     *  Holds the qualified form for every tag and the short form only for a
+     *  gameId no other tag shares. */
+    accept: Map<string, string>;
+    /** A tag gameId more than one box uses -> its qualified forms, in bundle
+     *  order. Empty for the overwhelming majority of projects, and what a
+     *  refusal lists. */
+    repeated: Map<string, string[]>;
+}
+/** The owner segment of every tag in the bundle, both ways round. */
+declare function valueAddresses(bundle: {
+    boxes: readonly {
+        id: string;
+        gameId?: string;
+        title?: string;
+        tagGroups: readonly TagGroup[];
+    }[];
+}): ValueAddresses;
+/** What an ambiguous short-form value address is told: the candidates, in
+ *  full, because "that names two tags" without them leaves a host reading a
+ *  bundle it did not write to find out which boxes. */
+declare function ambiguousValueAddressMessage(segment: string, name: string, candidates: readonly string[]): string;
 /**
  * The first free gameId of the form `base`, `base-2`, `base-3`, ... not already
  * in `taken`.
@@ -473,6 +519,17 @@ declare function byDisplayOrder<T extends {
     order?: number;
 }>(items: readonly T[]): T[];
 declare function freeTitle(base: string, taken: ReadonlySet<string>): string;
+/**
+ * A count of a TIMED box's turns, said as time (design/engine-server.md 4.8):
+ * `turnSpan(30, 60)` is "30 min", and `turnSpan(30, 60, true)` is "30 minutes".
+ *
+ * One definition, because the conversion appears wherever a designer might
+ * otherwise have to do it in their head: the card editor's Redraw field, the
+ * box page, the Board's advance buttons, and the coverage report's turn
+ * budget. Two of those want the unit spelled out and two want it short, which
+ * is the whole of `long`.
+ */
+declare function turnSpan(turns: number, seconds: number, long?: boolean): string;
 interface Outcome<E> {
     id: string;
     gameId?: string;
@@ -488,6 +545,11 @@ interface Outcome<E> {
     /** Target ("@scope.name") -> expression; all right-hand sides evaluate
      *  against pre-play state (schema 3.7). */
     changes: Record<string, E>;
+    /** Template data, as `Card.fields` is: field name -> value, declared by
+     *  the box's `outcomeFields`, validated at publish, and handed to the host
+     *  with the outcome. The engine never reads it: a press can say one line
+     *  ("The notice is in your pocket") without spending a card on it. */
+    fields?: Record<string, ScalarValue>;
 }
 interface Card<E> {
     id: string;
@@ -528,6 +590,21 @@ interface Card<E> {
      *  common case writes one number and "five in the world, one to a customer"
      *  is `copies: 1, sharedCopies: 5`. */
     sharedCopies?: number;
+    /** Does this card's `redraw: "never"` spend survive the run
+     *  (design/engine-server.md 4.2)? Absent takes the deck's flag, set here it
+     *  overrides the deck, exactly as `shared` does. `shared` decides who a
+     *  spend counts for WITHIN a run; this decides whether it outlives one.
+     *
+     *  Only `"never"` crosses the run boundary, for the reason only `"never"`
+     *  crosses the flow boundary (shared-scarcity 9.3.2): a finite cooldown is
+     *  an absolute turn of a box clock, and the clock resets with the run. On
+     *  any other redraw the flag is a compile warning.
+     *
+     *  INERT TO THE RUNTIME, like the declaration flag: the server lifts the
+     *  durable spends at run end (per-flow ones from the flow's `never`
+     *  cooldowns, shared ones from the engine's spent set) and puts them back
+     *  through `openFlow(id, { restore })` and `markTaken`. */
+    durable?: boolean;
     /** Card-template data: field name -> value, validated at publish. */
     fields?: Record<string, ScalarValue>;
     outcomes: Outcome<E>[];
@@ -543,6 +620,11 @@ interface Deck<E> {
      *  in it is shared unless the card says otherwise. The container is where
      *  Patter puts its own shared-memory flag, and the deck is our container. */
     shared?: boolean;
+    /** Every `redraw: "never"` card in this pile is spent for good, past the end
+     *  of the run, unless the card says otherwise (design/engine-server.md 4.2).
+     *  The container carries the flag for the reason `shared` is carried here:
+     *  a pile is what an author reaches for when a rule is true of all of it. */
+    durable?: boolean;
     properties: PropertyDecl[];
     cards: Card<E>[];
 }
@@ -638,6 +720,30 @@ interface TagGroup {
  *  half of that answer. `home` was a metaphor an author had to learn, and it
  *  leaked into hand-edited shards and the docs. */
 declare const PLACE_GROUP = "place";
+/** The scopes a movable hole may be filled from (design/engine-server.md 4.6):
+ *  the two `boundBy` already allows, plus `@hand` - the asking hand's OWN
+ *  declared property, resolved before tag composition so a movable hole can
+ *  never depend on the tags it is choosing. */
+type HoleRefScope = "hand" | "story" | "world";
+/** A parsed hole reference: `@hand.zone` -> `{ scope: "hand", name: "zone" }`. */
+interface HoleRef {
+    scope: HoleRefScope;
+    name: string;
+}
+/**
+ * Is this `chosen` / binding value MEANT as a property reference rather than a
+ * tag id?
+ *
+ * The test is the leading `@` alone, deliberately: a value that starts with
+ * one and does not parse is a mistyped reference, which the compiler should
+ * name as such, not a tag id that happens to look odd. Tag ids never begin
+ * with `@`.
+ */
+declare const isHoleRef: (value: string) => boolean;
+/** Parse a hole reference, or undefined when it is not one. The on-disk form
+ *  stays a plain string, so the canonical serialiser and the shard merge need
+ *  no change at all: a hole is still one group name against one value. */
+declare const parseHoleRef: (value: string) => HoleRef | undefined;
 /** A declared kind of hand (schema 2.6): live-inherited, author-side only,
  *  never called from game code. One condition governs every instance. */
 interface HandTemplate<E> {
@@ -649,9 +755,12 @@ interface HandTemplate<E> {
      *  position). Merges as a per-item value, so id-sorted storage stays
      *  merge-clean (Reboot 7.4). */
     order?: number;
-    /** Fixed tag bindings: tag group id -> tag id. */
+    /** Fixed tag bindings: tag group id -> tag id. Literal tags only: what a
+     *  template FIXES is the same for every instance, and a hole that moves is
+     *  the instance's own business (`Hand.chosen`, 4.6). */
     bindings?: Record<string, string>;
-    /** The holes: tag group ids each instance fills (one tag each). */
+    /** The holes: tag group ids each instance fills (one tag each, or one
+     *  property reference: 4.6). */
     chooses?: string[];
     /** Shared availability condition, ANDed in (schema 3.1); evaluated per
      *  instance against that instance's composed @hand. */
@@ -663,6 +772,15 @@ interface HandTemplate<E> {
 }
 /** A standalone hand's inline rule (schema 2.6): owned by the hand. */
 interface HandRule<E> {
+    /**
+     * Tag group id -> tag id, or a PROPERTY REFERENCE (`"@hand.zone"`,
+     * `"@story.where"`, `"@world.place"`) the runtime resolves at ask time
+     * (design/engine-server.md 4.6, the hand that moves). Still a plain string
+     * on disk, so the canonical serialiser and the merge are untouched; what
+     * widened is the meaning, and `parseHoleRef` is where it is read.
+     *
+     * `place` is never fillable this way: it is the hand's own name, not an axis.
+     */
     bindings?: Record<string, string>;
     condition?: E;
     slots: number | "unbounded";
@@ -679,7 +797,17 @@ interface Hand<E> {
     purpose?: string;
     /** Hand template id (not gameId). */
     template?: string;
-    /** Template instances: tag group id -> tag id, one per `chooses` hole. */
+    /**
+     * Template instances: tag group id -> tag id, one per `chooses` hole.
+     *
+     * A value may instead be a PROPERTY REFERENCE (`"@hand.zone"`,
+     * `"@story.where"`, `"@world.place"`), which makes the hole MOVABLE: the
+     * runtime resolves the reference at ask time and binds the hole to the tag
+     * the value names, so moving the Elder to the forest is `setProperty` and
+     * nothing else (design/engine-server.md 4.6). Still a plain string on disk,
+     * so the canonical serialiser and the shard merge need no change; read it
+     * with `parseHoleRef`.
+     */
     chosen?: Record<string, string>;
     /** Standalone hands: the inline rule. */
     rule?: HandRule<E>;
@@ -704,8 +832,31 @@ interface Box<E> {
     ranking: {
         specificity: boolean;
     };
+    /**
+     * A TIMED box: its clock counts real time, one turn every `seconds` of the
+     * run (design/engine-server.md 4.8). Absent is the ordinary box, whose turn
+     * is a play.
+     *
+     * Two things follow, and only two. In the ENGINE, a play in this box
+     * defaults to advancing nothing: `settings.playAdvancesTurns` does not
+     * apply, so a designer cannot declare the convention and then forget to
+     * switch play-advance off. Everywhere else it is what the tools SAY: the
+     * host ticks the box (the runtime has no clock and gains none here), and a
+     * card's `redraw: N` reads as N x `seconds`, which the editors, the bundle
+     * inspectors and the coverage report spell out rather than leaving a
+     * designer to know that 30 meant minutes.
+     *
+     * The number itself is inert to the runtime, which never reads it.
+     */
+    turn?: {
+        seconds: number;
+    };
     /** The card template: what every card in this box carries. */
     fields: FieldDecl[];
+    /** What every outcome in this box may carry, declared the same way.
+     *  Absent when the box declares none, so a bundle without them is byte for
+     *  byte what it was. */
+    outcomeFields?: FieldDecl[];
     properties: PropertyDecl[];
     tagGroups: TagGroup[];
     decks: Deck<E>[];
@@ -723,6 +874,30 @@ interface BundleContent {
 interface BundleSettings {
     playAdvancesTurns: number;
 }
+/**
+ * The play ladder (design/engine-server.md 4.10): how much of itself
+ * Storyletter shows this project, in one setting with three rungs rather than
+ * a set of toggles, because the features nest.
+ *
+ *   solo   one player, one flow: no sharing, no durability, no venue features
+ *   shared several players over one world: sharing appears
+ *   venue  a production: nothing is hidden
+ *
+ * EDITOR-SIDE ONLY. It stays in the project shard beside `coverage` and
+ * `export` and is never compiled: a solo project plays on the same Engine as a
+ * venue one. Hidden is hidden rather than disabled, so going DOWN a rung is
+ * refused when the project already contains what the rung would hide, and a
+ * hand-edited shard above its rung is a compile warning.
+ */
+type PlayRung = "solo" | "shared" | "venue";
+/** The default rung: a project shard that says nothing is a solo game. */
+declare const DEFAULT_PLAY_RUNG: PlayRung;
+/** The project shard's settings block: what the bundle carries, plus the
+ *  authoring-side play rung that it does not. */
+interface ProjectSettings extends BundleSettings {
+    /** The play ladder rung (see `PlayRung`). Absent = "solo". */
+    play?: PlayRung;
+}
 /**
  * A map that a bundle was asked to carry: one spatial tag group's geometry,
  * flattened for a host to draw (design/graphical-views.md 2, "The map MAY ship").
@@ -737,9 +912,16 @@ interface BundleSettings {
  * names it passes to `peek`. There is nothing here to strip either, which is why
  * `metadata: "stripped"` needs no special case: no titles, no purposes.
  *
- * Sites are deliberately NOT here. A site is where an author parked a hand while
- * working, held in the view sidecar precisely because it is not content, and a
- * host that wants to place a hand already has its zone from the compiled binding.
+ * SITES ARE HERE, which reverses a ruling. Until 2026-09-05 this comment said
+ * they were deliberately not: a site was where an author parked a hand while
+ * working, held in the view sidecar precisely because it was not content, and a
+ * host that wanted to place a hand had its zone from the compiled binding. That
+ * held for a game, where a hand's zone is its only real-world meaning. It does
+ * not hold for a physical experience (design/engine-server.md 4.3), where the
+ * position IS content: it is where the kiosk stands, and a producer's map is
+ * simply wrong without it. The alternative was a second file beside the bundle,
+ * which would cost a format the inspectors do not read and would put the view
+ * sidecar in the shipping path by the back door.
  */
 interface BundleMap {
     /** The owning box, by gameId (tag groups are box-scoped). */
@@ -755,6 +937,16 @@ interface BundleMap {
     /** Background pictures, back to front, as bundle-relative paths. Hidden ones
      *  do not ship: what an author put away is not something to spring on a host. */
     backgrounds?: BundleBackground[];
+    /** Where the placed hands stand on this map, by hand gameId, sorted by that
+     *  gameId so the bytes do not depend on authoring order. A hand nobody has
+     *  placed has no entry, and a map with no placed hand has no key at all. The
+     *  zone a site sits in is NOT repeated here: the hand's own binding is what
+     *  the runtime deals from, and a second copy could only go on to disagree. */
+    sites?: {
+        hand: string;
+        x: number;
+        y: number;
+    }[];
 }
 /** One shipped picture. `locked` and `hidden` are authoring state and do not
  *  travel; the draw order is the array order. */
@@ -844,6 +1036,75 @@ interface SaveEnvelope {
     shared: SharedSave;
     flows: Record<string, FlowSave>;
 }
+/** One card that a restore refused to put back on the board.
+ *
+ *  `vanished` and `hand-vanished` are the edit's doing (the card, or the hand
+ *  it sat in, is no longer in the bundle). `claimed-elsewhere` is only ever a
+ *  single-flow restore into a LIVE engine: the card is shared, and the other
+ *  open flows already hold every copy the world has. */
+interface LoadEviction {
+    flow: string;
+    hand: string;
+    card: string;
+    reason: "vanished" | "hand-vanished" | "claimed-elsewhere";
+}
+/** One property the restore could not put back as it was. `flow` names the
+ *  flow whose half it belongs to; absent, it is the shared half.
+ *
+ *  `path` is the engine's property address, spelled exactly as
+ *  `Flow.listProperties()` / `Engine.listProperties()` print it and exactly as
+ *  `getProperty` and `setProperty` accept it: `story.<name>` for the story
+ *  scope, `<scope>.<ownerGameId>.<name>` for the box, deck, hand and tag
+ *  scopes. No `@`, which belongs to the expression language and not to an
+ *  address.
+ *
+ *  The owner segment is its GAMEID (design/engine-server.md 4.4), the name it
+ *  is called by everywhere else, so an operator reading a hot-swap report can
+ *  paste the address straight into `setProperty`. An owner the build no longer
+ *  has keeps the id the save carried: there is no gameId left to give it,
+ *  which is the rule the eviction list above has always used. */
+interface LoadProperty {
+    flow?: string;
+    path: string;
+}
+/** What a load or a flow restore would do that is not a plain restore
+ *  (design/engine-server.md 4.9). Arrays are sorted, so two runtimes given the
+ *  same save and bundle produce the same bytes; `flows` alone keeps the
+ *  envelope's own order, because a caller re-takes its handles in it. */
+interface LoadReport {
+    /** No drift and nothing dropped, defaulted or retyped: the save goes back
+     *  exactly as it was. `flows` is not a divergence and does not count. */
+    exact: boolean;
+    project: string;
+    /** Drift when the two differ; reported, never refused. */
+    version: {
+        saved: string;
+        bundle: string;
+    };
+    /** Drift when the two differ; reported, never refused. */
+    hash: {
+        saved: string;
+        bundle: string;
+    };
+    /** The flows this restores, in the order it restores them. */
+    flows: string[];
+    evicted: LoadEviction[];
+    /** Cooldowns held for cards the bundle no longer has. */
+    droppedCooldowns: {
+        flow: string;
+        card: string;
+    }[];
+    /** Shared `redraw: "never"` entries for cards the bundle no longer has. */
+    droppedSpent: string[];
+    /** In the save, not declared any more. */
+    droppedProperties: LoadProperty[];
+    /** Declared, not in the save: it takes the declaration's default. */
+    defaultedProperties: LoadProperty[];
+    /** In the save, still declared, but the saved value no longer fits the
+     *  declaration (its type changed, or an enum value / quality stage was
+     *  edited away). It takes the declaration's default. */
+    retypedProperties: LoadProperty[];
+}
 /** The .storyletsave FILE: the HOST's file, not the engine's - the engine's
  *  envelope plus, when the host keeps one, its @world container. This is
  *  "host saves its container once, each engine saves its own envelope"
@@ -876,11 +1137,22 @@ declare const SHARD_EXTENSIONS: {
     readonly tags: ".storylettags";
     readonly hands: ".storylethands";
     readonly deck: ".storyletdeck";
-    /** The arrangement layer: where things SIT, never what they are. Its own shard
-     *  because positions churn (an afternoon of tidying a canvas touches every
-     *  card) and content does not, so a designer arranging and a writer editing
-     *  never collide on one file (design/graphical-views.md section 1.2). */
+    /** The AUTHOR's arrangement layer: the canvases, where cards sit on a deck's
+     *  node canvas and the furniture drawn round them. Its own shard because
+     *  positions churn (an afternoon of tidying a canvas touches every card) and
+     *  content does not, so a designer arranging and a writer editing never
+     *  collide on one file (design/graphical-views.md section 1.2). */
     readonly view: ".storyletview";
+    /** The DESIGNER's map: where a box's hands stand in space, and the furniture
+     *  round them. One per box, beside the view shard.
+     *
+     *  Split out of the view shard on 2026-09-06 (design/engine-server.md 9.1
+     *  point 5) because the two halves stopped having one owner. A hand's
+     *  position ships in the bundle's `maps` block (4.3) and is where a venue's
+     *  kiosk stands, so it is SHAPE, which a server's author key may not change;
+     *  the canvases are the author's own working drawing and never leave the
+     *  project folder. One file could not be both. */
+    readonly map: ".storyletmap";
     /** Threaded comments: content-ADJACENT, so neither in a content shard (a
      *  writer's deck edit must not conflict with a reviewer's comment) nor in the
      *  arrangement sidecar (this is not where anything sits). One per box,
@@ -888,16 +1160,94 @@ declare const SHARD_EXTENSIONS: {
      *  file and were retired: `purpose` already says why a thing exists, and
      *  Patterpad's typed routing has no destination here. */
     readonly notes: ".storyletnotes";
+    /** An installation contract: what a VENUE depends on, one file per
+     *  installation in `contracts/` at the project root
+     *  (design/engine-server.md 4.11). Its own shard, and its own folder, for the
+     *  walkthrough's reason (Reboot 7.5, S4): a different owner, a different
+     *  change rate, and a merge that must never collide with the author's edits,
+     *  since the server always wins its own file. */
+    readonly contract: ".storyletcontract";
 };
+/** Where the installation contracts live, relative to the project root. The
+ *  directory is the registry, as it is for a box's decks: a contract exists
+ *  because its file exists. */
+declare const CONTRACTS_DIR = "contracts";
 declare const PROJECT_SCHEMA = "storylets/project@0";
 declare const BOX_SCHEMA = "storylets/box@0";
 declare const TAGS_SCHEMA = "storylets/tags@0";
 declare const HANDS_SCHEMA = "storylets/hands@0";
 declare const DECK_SCHEMA = "storylets/deck@0";
 declare const VIEW_SCHEMA = "storylets/view@0";
+declare const MAP_SCHEMA = "storylets/map@0";
 /** The comment sidecar's schema. Still called "notes" on disk: the file already
  *  held both, and renaming it would break every project for no gain. */
 declare const NOTES_SCHEMA = "storylets/notes@0";
+declare const CONTRACT_SCHEMA = "storylets/contract@0";
+/**
+ * What one installation depends on, written by the venue's server and read by
+ * `validate` (design/engine-server.md 4.11).
+ *
+ * NOT THE AUTHOR'S FILE. A venue is provisioned against names - the hands its
+ * stations deal, the boxes its scheduler ticks, the properties its clocks drive,
+ * the fields its crew read - and the server writes them out so the tools that
+ * already gate a build can refuse a rename before it reaches the venue. A
+ * project playing at two venues has two of these. The author never edits one,
+ * and today, with no server built, a project either receives one or has none.
+ *
+ * NEVER COMPILED. It is project-side config like `coverage` and `export`: the
+ * server does not need its own contract handed back, it needs the bundle to
+ * still honour it.
+ *
+ * BY GAMEID throughout, because a gameId is the name that crosses the project's
+ * border and an internal id is authoring identity.
+ */
+interface ContractShard {
+    schema: typeof CONTRACT_SCHEMA;
+    /** The installation this contract speaks for. One file per installation, and
+     *  two files naming the same one is an error. */
+    installation: string;
+    /** Who wrote it, for a human reading the file ("Storylet Server 0.1.0"). */
+    by?: string;
+    /** The server's revision when it wrote this. */
+    revision?: number;
+    /** Hands a station is bound to, by gameId: they may not be renamed or
+     *  removed. */
+    hands?: string[];
+    /** Timed boxes the venue's scheduler ticks, by box gameId, with the turn unit
+     *  in SECONDS it was provisioned against. A box whose unit changed means every
+     *  rest on its cards changed meaning. */
+    boxes?: Record<string, {
+        turn: number;
+    }>;
+    /** Property paths the venue reads or drives, in the engine's own address
+     *  grammar with no `@` ("world.time_wall", "story.visits"), which is how
+     *  `listProperties()` prints them. */
+    properties?: ContractProperty[];
+    /** Card-template field names the crew and the bridges read. */
+    fields?: string[];
+    /** Outcome field names they read, the same way: the after-line a station
+     *  shows when a press lands. What `fields` is to the card template, this is
+     *  to the box's `outcomeFields`. */
+    outcomeFields?: string[];
+}
+/**
+ * One contracted property.
+ *
+ * A bare path is the common form and the one the spec's example writes. The
+ * object form adds the TYPE the venue was provisioned against, which is the only
+ * way `validate` can catch the break that costs a producer most: a property that
+ * still exists under the same name and now holds something else. A server that
+ * knows the type should write the object form; a hand-written contract may say
+ * only the path and get the existence check alone.
+ */
+type ContractProperty = string | {
+    path: string;
+    type?: PropertyType;
+};
+/** The path a contracted property names, whichever form it was written in. */
+declare const contractPropertyPath: (p: ContractProperty) => string;
+/** The type a contracted property was provisioned against, when it says. */
+declare const contractPropertyType: (p: ContractProperty) => PropertyType | undefined;
 /** A point in a canvas's own coordinates. */
 interface ViewPoint {
     x: number;
@@ -960,7 +1310,9 @@ interface DeckCanvas extends CanvasFurniture {
     /** Keyed by CARD id. */
     cards?: Record<string, ViewPoint>;
 }
-/** The box's map: where its hands sit in space, and the furniture around them. */
+/** The box's map: where its hands sit in space, and the furniture around them.
+ *  Carried by the MAP shard since 2026-09-06; `ViewShard.map` is the old
+ *  address, read for one release and never written. */
 interface BoxMap extends CanvasFurniture {
     /** Keyed by HAND id. WHERE a site is, and nothing else.
      *
@@ -976,7 +1328,8 @@ interface BoxMap extends CanvasFurniture {
      *  were edited. */
     sites?: Record<string, ViewPoint>;
 }
-/** The arrangement layer for one box: where things SIT, never what they are.
+/** The AUTHOR's arrangement layer for one box: where cards sit on their decks'
+ *  canvases, and the furniture drawn round them.
  *
  *  Its own shard on purpose (design/graphical-views.md section 1.2). Positions
  *  churn, content does not: an afternoon of tidying a canvas touches every card,
@@ -991,8 +1344,33 @@ interface ViewShard {
     schema: typeof VIEW_SCHEMA;
     /** Keyed by DECK id: one node canvas each. */
     canvases?: Record<string, DeckCanvas>;
+    /** @deprecated The box map's old address, kept for one release and READ ONLY.
+     *  A reader that meets it uses it when the box has no `MapShard`, and the
+     *  formatter moves it; nothing writes it any more. Removed after the next
+     *  release, at which point a map left here is simply lost. */
     map?: BoxMap;
 }
+/** The DESIGNER's map for one box: where its hands stand in space.
+ *
+ *  Split out of the view shard on 2026-09-06 (design/engine-server.md 9.1 point
+ *  5). The two halves had stopped sharing an owner: a hand's position ships in
+ *  the bundle's `maps` block (4.3), which makes it the thing a venue provisions
+ *  its kiosks against, while a deck's canvas is a working drawing that never
+ *  leaves the folder. A server's author key may change the canvases and not
+ *  this.
+ *
+ *  The map is NESTED under `map` rather than flattened to the top level, and
+ *  deliberately: the block's bytes are then exactly what the view shard held, so
+ *  the migration is a move of a value rather than a reshaping of it, the merge
+ *  strategy carries over word for word, and a reader that has to look in both
+ *  places is one expression (`box.map?.map ?? box.view?.map`).
+ *
+ *  Source-only in the sense the view shard is not: `compileMaps` reads the
+ *  positions for the bundle's `maps` block, under `export.map`. */
+interface MapShard {
+    schema: typeof MAP_SCHEMA;
+    map: BoxMap;
+}
 /** A coverage input driver: during a coverage run the harness feeds a
  *  host-seam property (`@world.x`) values from `values`, so content gated on
  *  external state gets exercised (Patter's coverageDrivers, carried whole). */
@@ -1017,7 +1395,7 @@ interface ProjectShard {
         name: string;
         version: string;
     };
-    settings: BundleSettings;
+    settings: ProjectSettings;
     /** Coverage drivers + argument domains (authoring/testing config; stays
      *  out of the compiled bundle). */
     coverage?: CoverageConfig;
@@ -1087,7 +1465,14 @@ interface BoxShard {
         ranking: {
             specificity: boolean;
         };
+        /** Declares a timed box (see `Box.turn`); compiled through unchanged. */
+        turn?: {
+            seconds: number;
+        };
         fields: FieldDecl[];
+        /** The outcome fields (see `Box.outcomeFields`); a shard without the key
+         *  declares none. */
+        outcomeFields?: FieldDecl[];
         properties: PropertyDecl[];
     };
 }
@@ -1112,6 +1497,8 @@ interface DeckShard {
         condition?: string;
         /** Scarce across flows: see Deck.shared. */
         shared?: boolean;
+        /** Its `redraw: "never"` cards are spent past the run: see Deck.durable. */
+        durable?: boolean;
         /** Authored display order within the box (sparse; see BoxShard). */
         order?: number;
         properties: PropertyDecl[];
@@ -1119,4 +1506,4 @@ interface DeckShard {
     cards: Card<string>[];
 }
 
-export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type Polygon, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ViewPoint, type ViewShard, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, unbindHand, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };
+export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, CONTRACTS_DIR, CONTRACT_SCHEMA, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type ContractProperty, type ContractShard, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, DEFAULT_PLAY_RUNG, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, type HoleRef, type HoleRefScope, type LoadEviction, type LoadProperty, type LoadReport, MAP_SCHEMA, type MapShard, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type PlayRung, type Polygon, type ProjectSettings, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ValueAddresses, type ViewPoint, type ViewShard, ambiguousValueAddressMessage, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, contractPropertyPath, contractPropertyType, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isHoleRef, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, parseHoleRef, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, turnSpan, unbindHand, valueAddresses, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };