@storylet-studio/model 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -23,9 +23,13 @@ __export(index_exports, {
   BOX_SCHEMA: () => BOX_SCHEMA,
   BUNDLE_EXTENSION: () => BUNDLE_EXTENSION,
   BUNDLE_SCHEMA: () => BUNDLE_SCHEMA,
+  CONTRACTS_DIR: () => CONTRACTS_DIR,
+  CONTRACT_SCHEMA: () => CONTRACT_SCHEMA,
   DECK_SCHEMA: () => DECK_SCHEMA,
+  DEFAULT_PLAY_RUNG: () => DEFAULT_PLAY_RUNG,
   FURNITURE_COLOURS: () => FURNITURE_COLOURS,
   HANDS_SCHEMA: () => HANDS_SCHEMA,
+  MAP_SCHEMA: () => MAP_SCHEMA,
   NOTES_SCHEMA: () => NOTES_SCHEMA,
   PLACE_GROUP: () => PLACE_GROUP,
   PROJECT_FOLDER_EXTENSION: () => PROJECT_FOLDER_EXTENSION,
@@ -37,12 +41,15 @@ __export(index_exports, {
   SPATIAL: () => SPATIAL,
   TAGS_SCHEMA: () => TAGS_SCHEMA,
   VIEW_SCHEMA: () => VIEW_SCHEMA,
+  ambiguousValueAddressMessage: () => ambiguousValueAddressMessage,
   backgroundsOf: () => backgroundsOf,
   bindHand: () => bindHand,
   bundleAssetPath: () => bundleAssetPath,
   byDisplayOrder: () => byDisplayOrder,
   centroid: () => centroid,
   commentsOf: () => commentsOf,
+  contractPropertyPath: () => contractPropertyPath,
+  contractPropertyType: () => contractPropertyType,
   droppedRect: () => droppedRect,
   effectiveGameId: () => effectiveGameId,
   framesOf: () => framesOf,
@@ -52,6 +59,7 @@ __export(index_exports, {
   handBinding: () => handBinding,
   inferDeclFromWrite: () => inferDeclFromWrite,
   isCaseOnlyPropertyName: () => import_expr.isCaseOnlyPropertyName,
+  isHoleRef: () => isHoleRef,
   isSpatial: () => isSpatial,
   isValidGameId: () => isValidGameId,
   isValidPropertyName: () => import_expr.isValidPropertyName,
@@ -59,6 +67,7 @@ __export(index_exports, {
   markOf: () => markOf,
   marksOn: () => marksOn,
   openThreadCounts: () => openThreadCounts,
+  parseHoleRef: () => parseHoleRef,
   pointInPolygon: () => pointInPolygon,
   polygonBounds: () => polygonBounds,
   polygonOf: () => polygonOf,
@@ -67,7 +76,9 @@ __export(index_exports, {
   spatialOf: () => spatialOf,
   stacked: () => stacked,
   threadsFor: () => threadsFor,
+  turnSpan: () => turnSpan,
   unbindHand: () => unbindHand,
+  valueAddresses: () => valueAddresses,
   withBackgrounds: () => withBackgrounds,
   withPolygon: () => withPolygon,
   withSpatialGroup: () => withSpatialGroup,
@@ -467,6 +478,41 @@ function effectiveGameId(entity) {
   const fromTitle = entity.title ? gameIdify(entity.title) : "";
   return fromTitle || entity.id;
 }
+function valueAddresses(bundle) {
+  const tags = [];
+  for (const box of bundle.boxes) {
+    const boxGameId = effectiveGameId(box);
+    for (const group of box.tagGroups) {
+      for (const tag of group.tags) {
+        const gameId = effectiveGameId(tag);
+        tags.push({ id: tag.id, gameId, qualified: `${boxGameId}/${gameId}` });
+      }
+    }
+  }
+  const forms = /* @__PURE__ */ new Map();
+  for (const tag of tags) {
+    const list = forms.get(tag.gameId) ?? [];
+    if (!list.includes(tag.qualified)) list.push(tag.qualified);
+    forms.set(tag.gameId, list);
+  }
+  const print = /* @__PURE__ */ new Map();
+  const accept = /* @__PURE__ */ new Map();
+  const repeated = /* @__PURE__ */ new Map();
+  for (const tag of tags) {
+    const candidates = forms.get(tag.gameId) ?? [tag.qualified];
+    const ambiguous = candidates.length > 1;
+    print.set(tag.id, ambiguous ? tag.qualified : tag.gameId);
+    if (!accept.has(tag.qualified)) accept.set(tag.qualified, tag.id);
+    if (!ambiguous && !accept.has(tag.gameId)) accept.set(tag.gameId, tag.id);
+    if (ambiguous) repeated.set(tag.gameId, candidates);
+  }
+  return { print, accept, repeated };
+}
+function ambiguousValueAddressMessage(segment, name, candidates) {
+  const forms = candidates.map((q) => `"value.${q}.${name}"`);
+  const list = forms.length <= 1 ? forms[0] ?? "" : `${forms.slice(0, -1).join(", ")} or ${forms[forms.length - 1]}`;
+  return `"value.${segment}.${name}" names a tag in ${candidates.length} boxes; write ${list}`;
+}
 function freeGameId(base, taken) {
   let gameId = base;
   for (let n = 2; taken.has(gameId); n++) gameId = `${base}-${n}`;
@@ -480,8 +526,32 @@ function freeTitle(base, taken) {
   for (let n = 2; taken.has(gameIdify(title)); n++) title = `${base} ${n}`;
   return title;
 }
+function turnSpan(turns, seconds, long = false) {
+  const total = Math.max(0, Math.round(turns * seconds));
+  const say = (n, short, one, many) => long ? `${n} ${n === 1 ? one : many}` : `${n} ${short}`;
+  if (total < 60) return long ? say(total, "s", "second", "seconds") : `${total}s`;
+  if (total < 3600) {
+    const minutes = total % 60 === 0 ? total / 60 : Math.round(total / 6) / 10;
+    return say(minutes, "min", "minute", "minutes");
+  }
+  let hours = Math.floor(total / 3600);
+  let rest = Math.round(total % 3600 / 60);
+  if (rest === 60) {
+    hours += 1;
+    rest = 0;
+  }
+  const said = say(hours, "hr", "hour", "hours");
+  return rest === 0 ? said : `${said} ${say(rest, "min", "minute", "minutes")}`;
+}
 var PLACE_GROUP = "place";
+var HOLE_REF = /^@(hand|world|story)\.([a-z][a-z0-9_-]*)$/;
+var isHoleRef = (value) => value.startsWith("@");
+var parseHoleRef = (value) => {
+  const m = HOLE_REF.exec(value);
+  return m === null ? void 0 : { scope: m[1], name: m[2] };
+};
 var BUNDLE_SCHEMA = "storylets/bundle@0";
+var DEFAULT_PLAY_RUNG = "solo";
 var SAVE_SCHEMA = "storylets/save@1";
 var SAVEFILE_SCHEMA = "storylets/savefile@1";
 var PROJECT_FOLDER_EXTENSION = ".storylets";
@@ -493,35 +563,62 @@ var SHARD_EXTENSIONS = {
   tags: ".storylettags",
   hands: ".storylethands",
   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). */
   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. */
+  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,
    *  id-keyed (design/annotation.md). Documentation NOTES used to share this
    *  file and were retired: `purpose` already says why a thing exists, and
    *  Patterpad's typed routing has no destination here. */
-  notes: ".storyletnotes"
+  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. */
+  contract: ".storyletcontract"
 };
+var CONTRACTS_DIR = "contracts";
 var PROJECT_SCHEMA = "storylets/project@0";
 var BOX_SCHEMA = "storylets/box@0";
 var TAGS_SCHEMA = "storylets/tags@0";
 var HANDS_SCHEMA = "storylets/hands@0";
 var DECK_SCHEMA = "storylets/deck@0";
 var VIEW_SCHEMA = "storylets/view@0";
+var MAP_SCHEMA = "storylets/map@0";
 var NOTES_SCHEMA = "storylets/notes@0";
+var CONTRACT_SCHEMA = "storylets/contract@0";
+var contractPropertyPath = (p) => typeof p === "string" ? p : p.path;
+var contractPropertyType = (p) => typeof p === "string" ? void 0 : p.type;
 var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BOX_SCHEMA,
   BUNDLE_EXTENSION,
   BUNDLE_SCHEMA,
+  CONTRACTS_DIR,
+  CONTRACT_SCHEMA,
   DECK_SCHEMA,
+  DEFAULT_PLAY_RUNG,
   FURNITURE_COLOURS,
   HANDS_SCHEMA,
+  MAP_SCHEMA,
   NOTES_SCHEMA,
   PLACE_GROUP,
   PROJECT_FOLDER_EXTENSION,
@@ -533,12 +630,15 @@ var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
   SPATIAL,
   TAGS_SCHEMA,
   VIEW_SCHEMA,
+  ambiguousValueAddressMessage,
   backgroundsOf,
   bindHand,
   bundleAssetPath,
   byDisplayOrder,
   centroid,
   commentsOf,
+  contractPropertyPath,
+  contractPropertyType,
   droppedRect,
   effectiveGameId,
   framesOf,
@@ -548,6 +648,7 @@ var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
   handBinding,
   inferDeclFromWrite,
   isCaseOnlyPropertyName,
+  isHoleRef,
   isSpatial,
   isValidGameId,
   isValidPropertyName,
@@ -555,6 +656,7 @@ var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
   markOf,
   marksOn,
   openThreadCounts,
+  parseHoleRef,
   pointInPolygon,
   polygonBounds,
   polygonOf,
@@ -563,7 +665,9 @@ var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
   spatialOf,
   stacked,
   threadsFor,
+  turnSpan,
   unbindHand,
+  valueAddresses,
   withBackgrounds,
   withPolygon,
   withSpatialGroup,