@patterkit/model 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  COMMON_GENDERS: () => COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER: () => DEFAULT_CAPTION_CHARACTER,
   DEFAULT_CAPTION_DELIMITERS: () => DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES: () => DEFAULT_DOCUMENTATION_CLASSES,
@@ -28,12 +29,16 @@ __export(index_exports, {
   PROJECT_LOCALE_SCENE: () => PROJECT_LOCALE_SCENE,
   RERECORD_STATUS: () => RERECORD_STATUS,
   RERECORD_STATUS_DECL: () => RERECORD_STATUS_DECL,
+  RESERVED_PROPERTY_NAMES: () => RESERVED_PROPERTY_NAMES,
   castStringKey: () => castStringKey,
   deriveRecordingFolders: () => deriveRecordingFolders,
   effectiveGameId: () => effectiveGameId,
   gameIdify: () => gameIdify,
+  isCaseOnlyPropertyName: () => isCaseOnlyPropertyName,
   isContentlessBeat: () => isContentlessBeat,
   isValidGameId: () => isValidGameId,
+  isValidPropertyName: () => isValidPropertyName,
+  propertyNameify: () => propertyNameify,
   walkNodes: () => walkNodes
 });
 module.exports = __toCommonJS(index_exports);
@@ -57,10 +62,27 @@ function gameIdify(text) {
 function isValidGameId(gameId) {
   return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(gameId);
 }
+var RESERVED_PROPERTY_NAMES = ["true", "false", "and", "or", "not"];
+function propertyNameify(text) {
+  const trimmed = text.trim();
+  const deliberateLeading = trimmed.startsWith("_");
+  let out = trimmed.toLowerCase().replace(/['\u2019]/g, "").replace(/[^a-z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  if (out === "") return "";
+  if (deliberateLeading || /^[0-9]/.test(out)) out = `_${out}`;
+  if (RESERVED_PROPERTY_NAMES.includes(out)) out = `${out}_`;
+  return out;
+}
+function isValidPropertyName(name) {
+  return /^[a-z_][a-z0-9_]*$/.test(name) && !RESERVED_PROPERTY_NAMES.includes(name);
+}
+function isCaseOnlyPropertyName(name) {
+  return !isValidPropertyName(name) && isValidPropertyName(name.toLowerCase());
+}
 function effectiveGameId(entity) {
   const g = entity.gameId?.trim();
   return g ? g : gameIdify(entity.name);
 }
+var COMMON_GENDERS = ["male", "female", "neuter"];
 var DEFAULT_WRITING_STATUSES = [
   { name: "stub", colour: 0 },
   // red
@@ -108,6 +130,7 @@ var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER,
   DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES,
@@ -116,11 +139,15 @@ var DEFAULT_CAPTION_CHARACTER = "SFX";
   PROJECT_LOCALE_SCENE,
   RERECORD_STATUS,
   RERECORD_STATUS_DECL,
+  RESERVED_PROPERTY_NAMES,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
   gameIdify,
+  isCaseOnlyPropertyName,
   isContentlessBeat,
   isValidGameId,
+  isValidPropertyName,
+  propertyNameify,
   walkNodes
 });

package/dist/index.d.cts

@@ -207,6 +207,21 @@ declare function isContentlessBeat(beat: Beat, hasText: boolean): boolean;
 declare function gameIdify(text: string): string;
 /** A valid authored game id: lowercase alphanumerics + hyphens, no leading / trailing hyphen. */
 declare function isValidGameId(gameId: string): boolean;
+/** The words `@wildwinter/expr` lexes as keywords, so no property may be called one.
+ *  `packages/model/test/property-name-grammar.test.ts` probes the real parser rather
+ *  than trusting this copy. */
+declare const RESERVED_PROPERTY_NAMES: readonly string[];
+/** Coerce a label into a legal property name: lower case, apostrophes dropped, runs of
+ *  anything else to a single underscore, no trailing underscore, an underscore in front
+ *  of a leading digit, one behind a keyword. "" when nothing usable was left. */
+declare function propertyNameify(text: string): string;
+/** Is this a name an expression can actually reach? Lower case letters, digits and
+ *  underscores, not starting with a digit, not a keyword. "" is not a name. */
+declare function isValidPropertyName(name: string): boolean;
+/** True when folding case ALONE would make it legal (`isNight`). The only violation a
+ *  loader may repair without guessing at intent: every reference is folded already, so
+ *  folding the declaration to match changes nothing observable. */
+declare function isCaseOnlyPropertyName(name: string): boolean;
 /** The effective address: the explicit `gameId` if pinned, else derived from `name`. */
 declare function effectiveGameId(entity: {
     gameId?: string;
@@ -296,8 +311,15 @@ interface CoverageDriver {
 /** A character's grammatical gender, for localisation. Translators need it to inflect the speaker's own
  *  lines in gendered languages (adjectives, participles, pronouns), which the source text alone often
  *  cannot tell them. Absent means "not specified". Authoring-only: it never reaches the runtime bundle,
- *  but it IS carried into the localisation handoff formats as translator context (spec §14). */
-type GrammaticalGender = "male" | "female" | "neuter";
+ *  but it IS carried into the localisation handoff formats as translator context (spec §14).
+ *
+ *  Free text, not a closed set: real languages need more than three genders (common/utrum, animate/
+ *  inanimate, and so on) and translators name them differently. `COMMON_GENDERS` seeds the editor's
+ *  auto-suggest so the everyday values stay spelled consistently; anything else is still valid. */
+type GrammaticalGender = string;
+/** The everyday grammatical genders the Cast editor offers as auto-suggest defaults. Not exhaustive and
+ *  not enforced - a project may use any string (see `GrammaticalGender`). */
+declare const COMMON_GENDERS: readonly ["male", "female", "neuter"];
 interface CastMember {
     /** Canonical speaker name (matched by a beat's `character`); language-neutral key. */
     name: string;
@@ -349,7 +371,7 @@ interface WritingStatusDecl {
     /** Threshold marker: this status and every later one classify as "ready to ship". */
     readyToShip?: boolean;
     /** Theme character-palette slot (0-11) for the per-line status badge / inspector swatch (Patterpad #196).
-     *  A slot (not a hex) so it adapts to light/dark + the reading palettes. Absent = no colour (neutral). */
+     *  A slot (not a hex) so it adapts to light/dark + the colour themes. Absent = no colour (neutral). */
     colour?: number;
 }
 /**
@@ -600,6 +622,17 @@ interface CommentMessage {
     author: string;
     ts: string;
     body: string;
+    /** A TOMBSTONE: the words are gone, the turn in the conversation is not.
+     *
+     *  Removing a reply outright would renumber the argument around it, so what is
+     *  left records who spoke and when, and that they withdrew it. The `body` is
+     *  EMPTIED rather than kept and hidden, because "deleted" has to mean gone from
+     *  a file that lives in version control.
+     *
+     *  This is the one message allowed an empty body: `saveSceneComments` prunes
+     *  empty messages so a cancelled composer leaves nothing behind, and without
+     *  this flag a tombstone would be pruned on the way to disk. */
+    deleted?: boolean;
 }
 /** A sub-text range a comment is pinned to, within its anchor node's say text (#148). Offsets are
  *  character positions over the rendered (plain) source text - inline formatting is marks, not part of
@@ -819,4 +852,4 @@ declare const DEFAULT_CAPTION_DELIMITERS: CaptionDelimiters;
  *  captions are off). Applies even to a project that pins no `closedCaptions`. */
 declare const DEFAULT_CAPTION_CHARACTER = "SFX";
 
-export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EstimatingConfig, type Expression, type FlowFile, type FlowNode, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SequenceOptions, type Snippet, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };
+export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EstimatingConfig, type Expression, type FlowFile, type FlowNode, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, RESERVED_PROPERTY_NAMES, type RecordingFolder, type RecordingStatusDecl, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SequenceOptions, type Snippet, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isCaseOnlyPropertyName, isContentlessBeat, isValidGameId, isValidPropertyName, propertyNameify, walkNodes };

package/dist/index.d.ts

@@ -207,6 +207,21 @@ declare function isContentlessBeat(beat: Beat, hasText: boolean): boolean;
 declare function gameIdify(text: string): string;
 /** A valid authored game id: lowercase alphanumerics + hyphens, no leading / trailing hyphen. */
 declare function isValidGameId(gameId: string): boolean;
+/** The words `@wildwinter/expr` lexes as keywords, so no property may be called one.
+ *  `packages/model/test/property-name-grammar.test.ts` probes the real parser rather
+ *  than trusting this copy. */
+declare const RESERVED_PROPERTY_NAMES: readonly string[];
+/** Coerce a label into a legal property name: lower case, apostrophes dropped, runs of
+ *  anything else to a single underscore, no trailing underscore, an underscore in front
+ *  of a leading digit, one behind a keyword. "" when nothing usable was left. */
+declare function propertyNameify(text: string): string;
+/** Is this a name an expression can actually reach? Lower case letters, digits and
+ *  underscores, not starting with a digit, not a keyword. "" is not a name. */
+declare function isValidPropertyName(name: string): boolean;
+/** True when folding case ALONE would make it legal (`isNight`). The only violation a
+ *  loader may repair without guessing at intent: every reference is folded already, so
+ *  folding the declaration to match changes nothing observable. */
+declare function isCaseOnlyPropertyName(name: string): boolean;
 /** The effective address: the explicit `gameId` if pinned, else derived from `name`. */
 declare function effectiveGameId(entity: {
     gameId?: string;
@@ -296,8 +311,15 @@ interface CoverageDriver {
 /** A character's grammatical gender, for localisation. Translators need it to inflect the speaker's own
  *  lines in gendered languages (adjectives, participles, pronouns), which the source text alone often
  *  cannot tell them. Absent means "not specified". Authoring-only: it never reaches the runtime bundle,
- *  but it IS carried into the localisation handoff formats as translator context (spec §14). */
-type GrammaticalGender = "male" | "female" | "neuter";
+ *  but it IS carried into the localisation handoff formats as translator context (spec §14).
+ *
+ *  Free text, not a closed set: real languages need more than three genders (common/utrum, animate/
+ *  inanimate, and so on) and translators name them differently. `COMMON_GENDERS` seeds the editor's
+ *  auto-suggest so the everyday values stay spelled consistently; anything else is still valid. */
+type GrammaticalGender = string;
+/** The everyday grammatical genders the Cast editor offers as auto-suggest defaults. Not exhaustive and
+ *  not enforced - a project may use any string (see `GrammaticalGender`). */
+declare const COMMON_GENDERS: readonly ["male", "female", "neuter"];
 interface CastMember {
     /** Canonical speaker name (matched by a beat's `character`); language-neutral key. */
     name: string;
@@ -349,7 +371,7 @@ interface WritingStatusDecl {
     /** Threshold marker: this status and every later one classify as "ready to ship". */
     readyToShip?: boolean;
     /** Theme character-palette slot (0-11) for the per-line status badge / inspector swatch (Patterpad #196).
-     *  A slot (not a hex) so it adapts to light/dark + the reading palettes. Absent = no colour (neutral). */
+     *  A slot (not a hex) so it adapts to light/dark + the colour themes. Absent = no colour (neutral). */
     colour?: number;
 }
 /**
@@ -600,6 +622,17 @@ interface CommentMessage {
     author: string;
     ts: string;
     body: string;
+    /** A TOMBSTONE: the words are gone, the turn in the conversation is not.
+     *
+     *  Removing a reply outright would renumber the argument around it, so what is
+     *  left records who spoke and when, and that they withdrew it. The `body` is
+     *  EMPTIED rather than kept and hidden, because "deleted" has to mean gone from
+     *  a file that lives in version control.
+     *
+     *  This is the one message allowed an empty body: `saveSceneComments` prunes
+     *  empty messages so a cancelled composer leaves nothing behind, and without
+     *  this flag a tombstone would be pruned on the way to disk. */
+    deleted?: boolean;
 }
 /** A sub-text range a comment is pinned to, within its anchor node's say text (#148). Offsets are
  *  character positions over the rendered (plain) source text - inline formatting is marks, not part of
@@ -819,4 +852,4 @@ declare const DEFAULT_CAPTION_DELIMITERS: CaptionDelimiters;
  *  captions are off). Applies even to a project that pins no `closedCaptions`. */
 declare const DEFAULT_CAPTION_CHARACTER = "SFX";
 
-export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EstimatingConfig, type Expression, type FlowFile, type FlowNode, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SequenceOptions, type Snippet, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };
+export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EstimatingConfig, type Expression, type FlowFile, type FlowNode, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, RESERVED_PROPERTY_NAMES, type RecordingFolder, type RecordingStatusDecl, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SequenceOptions, type Snippet, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isCaseOnlyPropertyName, isContentlessBeat, isValidGameId, isValidPropertyName, propertyNameify, walkNodes };

package/dist/index.js

@@ -19,10 +19,27 @@ function gameIdify(text) {
 function isValidGameId(gameId) {
   return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(gameId);
 }
+var RESERVED_PROPERTY_NAMES = ["true", "false", "and", "or", "not"];
+function propertyNameify(text) {
+  const trimmed = text.trim();
+  const deliberateLeading = trimmed.startsWith("_");
+  let out = trimmed.toLowerCase().replace(/['\u2019]/g, "").replace(/[^a-z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  if (out === "") return "";
+  if (deliberateLeading || /^[0-9]/.test(out)) out = `_${out}`;
+  if (RESERVED_PROPERTY_NAMES.includes(out)) out = `${out}_`;
+  return out;
+}
+function isValidPropertyName(name) {
+  return /^[a-z_][a-z0-9_]*$/.test(name) && !RESERVED_PROPERTY_NAMES.includes(name);
+}
+function isCaseOnlyPropertyName(name) {
+  return !isValidPropertyName(name) && isValidPropertyName(name.toLowerCase());
+}
 function effectiveGameId(entity) {
   const g = entity.gameId?.trim();
   return g ? g : gameIdify(entity.name);
 }
+var COMMON_GENDERS = ["male", "female", "neuter"];
 var DEFAULT_WRITING_STATUSES = [
   { name: "stub", colour: 0 },
   // red
@@ -69,6 +86,7 @@ function castStringKey(name) {
 var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
 export {
+  COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER,
   DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES,
@@ -77,11 +95,15 @@ export {
   PROJECT_LOCALE_SCENE,
   RERECORD_STATUS,
   RERECORD_STATUS_DECL,
+  RESERVED_PROPERTY_NAMES,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
   gameIdify,
+  isCaseOnlyPropertyName,
   isContentlessBeat,
   isValidGameId,
+  isValidPropertyName,
+  propertyNameify,
   walkNodes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/model",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Patter data-model types: source (scene/block/group/snippet/beat/jump), project, locale, authoring. The shape source-of-truth.",
   "type": "module",
   "license": "MIT",