@patterkit/core 0.2.5 → 0.3.0

package/dist/index.cjs

@@ -29,6 +29,8 @@ __export(index_exports, {
   isValidGameId: () => import_model4.isValidGameId,
   newId: () => import_toolkit.newId,
   parseSource: () => import_toolkit3.parseSource,
+  planProject: () => planProject,
+  planScene: () => planScene,
   slug: () => slug,
   validateProject: () => validateProject
 });
@@ -472,6 +474,76 @@ function defaultMatchesType(value, decl) {
       return typeof value === "string" && (decl.stages?.includes(value) ?? true);
   }
 }
+
+// src/scene-scaffold.ts
+var trimSlash = (p) => p.replace(/\/+$/, "");
+function planProject(opts) {
+  const locale = opts.locale ?? "en";
+  const project = {
+    schema: "patter/project@0",
+    project: { id: (0, import_toolkit.newId)("proj"), name: opts.name },
+    locales: { default: locale, all: [locale] },
+    voiced: true
+  };
+  return { path: `${slug(opts.name) || "project"}.patterproj`, content: canonicalStringify(project) };
+}
+function planScene(target, scaffold) {
+  const base = slug(scaffold.gameId) || slug(scaffold.name) || "scene";
+  let stem = base;
+  for (let n = 2; target.takenStems.has(stem); n++) stem = `${base}-${n}`;
+  const strings = {};
+  const say = (prefix, text) => {
+    const id = (0, import_toolkit.newId)(prefix);
+    strings[id] = text;
+    return { id, kind: "text" };
+  };
+  const opening = {
+    id: (0, import_toolkit.newId)("sn"),
+    type: "snippet",
+    beats: [say("T", scaffold.opening?.trim() || `Write the scene for "${scaffold.name}" here.`)]
+  };
+  const children = [opening];
+  if (scaffold.outcomes.length <= 1) {
+    opening.jump = { to: "END" };
+  } else {
+    children.push({
+      id: (0, import_toolkit.newId)("g"),
+      type: "group",
+      selector: "choice",
+      children: scaffold.outcomes.map((o) => ({
+        id: (0, import_toolkit.newId)("opt"),
+        type: "group",
+        prompt: say("L", o.title?.trim() || o.gameId),
+        gameData: { outcome: o.gameId },
+        children: [{
+          id: (0, import_toolkit.newId)("sn"),
+          type: "snippet",
+          beats: [say("T", "What happens next.")],
+          jump: { to: "END" }
+        }]
+      }))
+    });
+  }
+  const sceneId = (0, import_toolkit.newId)("scn");
+  const scene = {
+    id: sceneId,
+    type: "scene",
+    name: scaffold.name,
+    gameId: scaffold.gameId,
+    blocks: [{ id: (0, import_toolkit.newId)("blk"), type: "block", name: "Main", children }]
+  };
+  const flow = { schema: "patter/flow@0", scene };
+  const locale = { schema: "patter/strings@0", scene: sceneId, locale: target.locale, default: true, strings };
+  const flowDir = trimSlash(target.layout?.flow ?? "scenes/");
+  const stringsDir = trimSlash(target.layout?.strings ?? "loc/");
+  return {
+    sceneId,
+    writes: [
+      { path: `${flowDir}/${stem}.patterflow`, content: canonicalStringify(flow) },
+      { path: `${stringsDir}/${target.locale}/${stem}.patterloc`, content: canonicalStringify(locale) }
+    ]
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   canonicalStringify,
@@ -483,6 +555,8 @@ function defaultMatchesType(value, decl) {
   isValidGameId,
   newId,
   parseSource,
+  planProject,
+  planScene,
   slug,
   validateProject
 });

package/dist/index.d.cts

@@ -40,4 +40,52 @@ interface ProjectInput {
 /** Validate a project's structural invariants. Returns an empty array when valid. */
 declare function validateProject(input: ProjectInput): ValidationIssue[];
 
-export { type ProjectInput, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, humanizeNodeRefs, slug, validateProject };
+interface SceneScaffold {
+    /** The scene's name: the card's title. */
+    name: string;
+    /** The scene's address, pinned: the card's gameId, so the pairing never depends on the name. */
+    gameId: string;
+    /** The opening narration: the card's purpose, say. A prompt to write the scene when absent. */
+    opening?: string;
+    /** The card's outcomes: `gameId` labels an option, `title` is its words. */
+    outcomes: ReadonlyArray<{
+        gameId: string;
+        title?: string;
+    }>;
+}
+interface ScenePlanTarget {
+    /** The project's layout (`ProjectFile.layout`); Patter's defaults when absent. */
+    layout?: {
+        flow?: string;
+        strings?: string;
+    };
+    /** The project's default locale: the strings go there. */
+    locale: string;
+    /** File stems already taken in the flow folder, so the new one doesn't collide. */
+    takenStems: ReadonlySet<string>;
+}
+interface ScenePlan {
+    sceneId: string;
+    /** Project-relative paths and canonical content: the flow shard, then its strings. */
+    writes: {
+        path: string;
+        content: string;
+    }[];
+}
+/**
+ * Plan a new, empty Patter project for another tool to create beside its own (Storyletter's
+ * "Starter project with Patter"): the project file as Patter's own init writes it, named after
+ * the project, in one locale. Scenes are added with `planScene`. Returns the project file's path
+ * relative to the new project folder, and its canonical content.
+ */
+declare function planProject(opts: {
+    name: string;
+    locale?: string;
+}): {
+    path: string;
+    content: string;
+};
+/** Plan a stub scene for a card. Pure: nothing is read or written. */
+declare function planScene(target: ScenePlanTarget, scaffold: SceneScaffold): ScenePlan;
+
+export { type ProjectInput, type ScenePlan, type ScenePlanTarget, type SceneScaffold, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, humanizeNodeRefs, planProject, planScene, slug, validateProject };

package/dist/index.d.ts

@@ -40,4 +40,52 @@ interface ProjectInput {
 /** Validate a project's structural invariants. Returns an empty array when valid. */
 declare function validateProject(input: ProjectInput): ValidationIssue[];
 
-export { type ProjectInput, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, humanizeNodeRefs, slug, validateProject };
+interface SceneScaffold {
+    /** The scene's name: the card's title. */
+    name: string;
+    /** The scene's address, pinned: the card's gameId, so the pairing never depends on the name. */
+    gameId: string;
+    /** The opening narration: the card's purpose, say. A prompt to write the scene when absent. */
+    opening?: string;
+    /** The card's outcomes: `gameId` labels an option, `title` is its words. */
+    outcomes: ReadonlyArray<{
+        gameId: string;
+        title?: string;
+    }>;
+}
+interface ScenePlanTarget {
+    /** The project's layout (`ProjectFile.layout`); Patter's defaults when absent. */
+    layout?: {
+        flow?: string;
+        strings?: string;
+    };
+    /** The project's default locale: the strings go there. */
+    locale: string;
+    /** File stems already taken in the flow folder, so the new one doesn't collide. */
+    takenStems: ReadonlySet<string>;
+}
+interface ScenePlan {
+    sceneId: string;
+    /** Project-relative paths and canonical content: the flow shard, then its strings. */
+    writes: {
+        path: string;
+        content: string;
+    }[];
+}
+/**
+ * Plan a new, empty Patter project for another tool to create beside its own (Storyletter's
+ * "Starter project with Patter"): the project file as Patter's own init writes it, named after
+ * the project, in one locale. Scenes are added with `planScene`. Returns the project file's path
+ * relative to the new project folder, and its canonical content.
+ */
+declare function planProject(opts: {
+    name: string;
+    locale?: string;
+}): {
+    path: string;
+    content: string;
+};
+/** Plan a stub scene for a card. Pure: nothing is read or written. */
+declare function planScene(target: ScenePlanTarget, scaffold: SceneScaffold): ScenePlan;
+
+export { type ProjectInput, type ScenePlan, type ScenePlanTarget, type SceneScaffold, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, humanizeNodeRefs, planProject, planScene, slug, validateProject };

package/dist/index.js

@@ -436,6 +436,76 @@ function defaultMatchesType(value, decl) {
       return typeof value === "string" && (decl.stages?.includes(value) ?? true);
   }
 }
+
+// src/scene-scaffold.ts
+var trimSlash = (p) => p.replace(/\/+$/, "");
+function planProject(opts) {
+  const locale = opts.locale ?? "en";
+  const project = {
+    schema: "patter/project@0",
+    project: { id: newId("proj"), name: opts.name },
+    locales: { default: locale, all: [locale] },
+    voiced: true
+  };
+  return { path: `${slug(opts.name) || "project"}.patterproj`, content: canonicalStringify(project) };
+}
+function planScene(target, scaffold) {
+  const base = slug(scaffold.gameId) || slug(scaffold.name) || "scene";
+  let stem = base;
+  for (let n = 2; target.takenStems.has(stem); n++) stem = `${base}-${n}`;
+  const strings = {};
+  const say = (prefix, text) => {
+    const id = newId(prefix);
+    strings[id] = text;
+    return { id, kind: "text" };
+  };
+  const opening = {
+    id: newId("sn"),
+    type: "snippet",
+    beats: [say("T", scaffold.opening?.trim() || `Write the scene for "${scaffold.name}" here.`)]
+  };
+  const children = [opening];
+  if (scaffold.outcomes.length <= 1) {
+    opening.jump = { to: "END" };
+  } else {
+    children.push({
+      id: newId("g"),
+      type: "group",
+      selector: "choice",
+      children: scaffold.outcomes.map((o) => ({
+        id: newId("opt"),
+        type: "group",
+        prompt: say("L", o.title?.trim() || o.gameId),
+        gameData: { outcome: o.gameId },
+        children: [{
+          id: newId("sn"),
+          type: "snippet",
+          beats: [say("T", "What happens next.")],
+          jump: { to: "END" }
+        }]
+      }))
+    });
+  }
+  const sceneId = newId("scn");
+  const scene = {
+    id: sceneId,
+    type: "scene",
+    name: scaffold.name,
+    gameId: scaffold.gameId,
+    blocks: [{ id: newId("blk"), type: "block", name: "Main", children }]
+  };
+  const flow = { schema: "patter/flow@0", scene };
+  const locale = { schema: "patter/strings@0", scene: sceneId, locale: target.locale, default: true, strings };
+  const flowDir = trimSlash(target.layout?.flow ?? "scenes/");
+  const stringsDir = trimSlash(target.layout?.strings ?? "loc/");
+  return {
+    sceneId,
+    writes: [
+      { path: `${flowDir}/${stem}.patterflow`, content: canonicalStringify(flow) },
+      { path: `${stringsDir}/${target.locale}/${stem}.patterloc`, content: canonicalStringify(locale) }
+    ]
+  };
+}
 export {
   canonicalStringify,
   effectiveGameId2 as effectiveGameId,
@@ -446,6 +516,8 @@ export {
   isValidGameId2 as isValidGameId,
   newId,
   parseSource,
+  planProject,
+  planScene,
   slug,
   validateProject
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/core",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Patter core: stable id generation, readable-handle computation, canonical (de)serialisation, and the structural validator.",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean"
   },
   "dependencies": {
-    "@patterkit/model": "0.6.0",
+    "@patterkit/model": "0.7.0",
     "@wildwinter/toolkit": "^0.1.0",
     "json5": "^2.2.3"
   }