@wildwinter/toolkit 0.2.3 → 0.2.5

package/dist/index.cjs

@@ -48,10 +48,49 @@ function findMatcher(opts) {
   const body = opts.wholeWord ? `\\b${esc}\\b` : esc;
   return new RegExp(body, opts.caseSensitive ? "g" : "gi");
 }
+function parseFieldQuery(query) {
+  const m = /^\s*([a-z_][\w-]*(?:\.[a-z_][\w-]*){0,2})\s*(?:(!=|=)\s*(.*?))?\s*$/i.exec(query);
+  if (!m) return null;
+  const field = m[1].toLowerCase();
+  if (m[2] === void 0) return { field };
+  let value = m[3];
+  const q = /^(["'])(.*)\1$/.exec(value);
+  if (q) value = q[2];
+  return { field, op: m[2], value };
+}
+var fieldNameMatches = (name, query) => name.toLowerCase() === query.field;
+function fieldValueMatches(type, value, query) {
+  if (query.op === void 0 || query.value === void 0) return true;
+  const holds = valueIs(type, value, query.value);
+  return query.op === "=" ? holds : !holds;
+}
+function valueIs(type, value, wanted) {
+  const want = wanted.trim().toLowerCase();
+  if (type === "flags") {
+    const flags = Array.isArray(value) ? value.map((f) => String(f).toLowerCase()) : [];
+    return want === "" ? flags.length === 0 : flags.includes(want);
+  }
+  if (type === "number") {
+    if (want === "") return value === void 0 || value === null || value === "";
+    const n = Number(want);
+    return !Number.isNaN(n) && typeof value === "number" && value === n;
+  }
+  if (type === "boolean") return value === true && want === "true" || value === false && want === "false";
+  return fieldValueText(type, value).trim().toLowerCase() === want;
+}
+function fieldValueText(type, value) {
+  if (value === void 0 || value === null) return "";
+  if (type === "flags" && Array.isArray(value)) return value.join(", ");
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
 
+exports.fieldNameMatches = fieldNameMatches;
+exports.fieldValueMatches = fieldValueMatches;
+exports.fieldValueText = fieldValueText;
 exports.findMatcher = findMatcher;
 exports.fnv32 = fnv32;
 exports.newId = newId;
+exports.parseFieldQuery = parseFieldQuery;
 exports.parseSource = parseSource;
 exports.slug = slug;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ids.ts","../src/hash.ts","../src/source.ts","../src/find.ts"],"names":["JSON5"],"mappings":";;;;;;;;;AASA,IAAM,QAAA,GAAW,sCAAA;AAGV,SAAS,KAAA,CAAM,MAAA,GAAS,EAAA,EAAI,MAAA,GAAS,CAAA,EAAW;AAGrD,EAAA,MAAM,KAAA,GAAQ,GAAA,GAAO,GAAA,GAAM,QAAA,CAAS,MAAA;AACpC,EAAA,IAAI,KAAA,GAAQ,EAAA;AACZ,EAAA,OAAO,KAAA,CAAM,SAAS,MAAA,EAAQ;AAC5B,IAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,MAAA,GAAS,CAAC,CAAA;AACvC,IAAA,UAAA,CAAW,MAAA,CAAO,gBAAgB,KAAK,CAAA;AACvC,IAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACrB,MAAA,IAAI,KAAK,KAAA,EAAO;AAChB,MAAA,KAAA,IAAS,QAAA,CAAS,CAAA,GAAI,QAAA,CAAS,MAAM,CAAA;AACrC,MAAA,IAAI,KAAA,CAAM,WAAW,MAAA,EAAQ;AAAA,IAC/B;AAAA,EACF;AACA,EAAA,OAAO,MAAA,GAAS,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,KAAK,CAAA,CAAA,GAAK,KAAA;AACzC;AAGO,SAAS,IAAA,CAAK,IAAA,EAAc,QAAA,GAAW,SAAA,EAAmB;AAC/D,EAAA,MAAM,CAAA,GAAI,IAAA,CAAK,IAAA,EAAK,CAAE,WAAA,EAAY,CAAE,OAAA,CAAQ,aAAA,EAAe,GAAG,CAAA,CAAE,OAAA,CAAQ,UAAA,EAAY,EAAE,CAAA;AACtF,EAAA,OAAO,CAAA,IAAK,QAAA;AACd;;;ACxBO,SAAS,MAAM,KAAA,EAAuB;AAC3C,EAAA,IAAI,CAAA,GAAI,UAAA;AACR,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,QAAQ,CAAA,EAAA,EAAK;AACrC,IAAA,CAAA,IAAK,KAAA,CAAM,WAAW,CAAC,CAAA;AACvB,IAAA,CAAA,GAAI,IAAA,CAAK,IAAA,CAAK,CAAA,EAAG,QAAU,CAAA;AAAA,EAC7B;AACA,EAAA,OAAO,CAAA,KAAM,CAAA;AACf;ACLO,SAAS,YAAY,IAAA,EAAuB;AACjD,EAAA,MAAM,IAAA,GAAO,KAAK,UAAA,CAAW,CAAC,MAAM,KAAA,GAAS,IAAA,CAAK,KAAA,CAAM,CAAC,CAAA,GAAI,IAAA;AAC7D,EAAA,OAAOA,sBAAA,CAAM,MAAM,IAAI,CAAA;AACzB;;;ACGO,SAAS,YAAY,IAAA,EAAkC;AAC5D,EAAA,IAAI,CAAC,IAAA,CAAK,KAAA,EAAO,OAAO,IAAA;AACxB,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,KAAA,CAAM,OAAA,CAAQ,uBAAuB,MAAM,CAAA;AAC5D,EAAA,MAAM,IAAA,GAAO,IAAA,CAAK,SAAA,GAAY,CAAA,GAAA,EAAM,GAAG,CAAA,GAAA,CAAA,GAAQ,GAAA;AAC/C,EAAA,OAAO,IAAI,MAAA,CAAO,IAAA,EAAM,IAAA,CAAK,aAAA,GAAgB,MAAM,IAAI,CAAA;AACzD","file":"index.cjs","sourcesContent":["// ---------------------------------------------------------------------------\n// Stable, immutable, opaque ids.\n//\n// Generated at creation, never derived from content or position, so an id\n// survives moving, renaming and reordering the thing it names. A short,\n// collision-resistant base-36 token with an optional type prefix that aids\n// debugging but carries no meaning.\n// ---------------------------------------------------------------------------\n\nconst ALPHABET = \"0123456789abcdefghijklmnopqrstuvwxyz\";\n\n/** Generate a new opaque id, e.g. `newId(\"scn\") -> \"scn_8f3kq2z1\"`. */\nexport function newId(prefix = \"\", length = 8): string {\n  // Rejection-sample so every alphabet character is equally likely: a plain\n  // `byte % 36` over-weights the first four characters.\n  const limit = 256 - (256 % ALPHABET.length); // 252\n  let token = \"\";\n  while (token.length < length) {\n    const bytes = new Uint8Array(length * 2);\n    globalThis.crypto.getRandomValues(bytes);\n    for (const b of bytes) {\n      if (b >= limit) continue;\n      token += ALPHABET[b % ALPHABET.length];\n      if (token.length === length) break;\n    }\n  }\n  return prefix ? `${prefix}_${token}` : token;\n}\n\n/** A url-ish slug from a human label; `\"project\"` when nothing usable is left. */\nexport function slug(name: string, fallback = \"project\"): string {\n  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\");\n  return s || fallback;\n}\n","// ---------------------------------------------------------------------------\n// FNV-1a, 32-bit.\n//\n// A published, fixed algorithm. Not cryptographic: it is for short stable\n// handles and change detection, where the properties that matter are that it is\n// the same everywhere and does not move between runs.\n// ---------------------------------------------------------------------------\n\n/** FNV-1a over a string's UTF-16 code units, as an unsigned 32-bit integer. */\nexport function fnv32(input: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n","// ---------------------------------------------------------------------------\n// Reading authored source files.\n// ---------------------------------------------------------------------------\n\nimport JSON5 from \"json5\";\n\n/**\n * Parse JSON5 source text. A leading byte-order mark is tolerated, because\n * editors on Windows add one and JSON5 will not accept it. Throws on malformed\n * input.\n */\nexport function parseSource(text: string): unknown {\n  const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n  return JSON5.parse(body);\n}\n","// ---------------------------------------------------------------------------\n// Find and replace over authored text.\n// ---------------------------------------------------------------------------\n\nexport interface FindOptions {\n  query: string;\n  caseSensitive?: boolean;\n  wholeWord?: boolean;\n}\n\n/**\n * Build the find matcher, or null for an empty query. Global, so every\n * occurrence in a string is replaced rather than only the first.\n *\n * The query is escaped: a person typing `a.b` means those three characters, not\n * \"a, anything, b\".\n */\nexport function findMatcher(opts: FindOptions): RegExp | null {\n  if (!opts.query) return null;\n  const esc = opts.query.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n  const body = opts.wholeWord ? `\\\\b${esc}\\\\b` : esc;\n  return new RegExp(body, opts.caseSensitive ? \"g\" : \"gi\");\n}\n"]}
+{"version":3,"sources":["../src/ids.ts","../src/hash.ts","../src/source.ts","../src/find.ts"],"names":["JSON5"],"mappings":"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","file":"index.cjs","sourcesContent":["// ---------------------------------------------------------------------------\n// Stable, immutable, opaque ids.\n//\n// Generated at creation, never derived from content or position, so an id\n// survives moving, renaming and reordering the thing it names. A short,\n// collision-resistant base-36 token with an optional type prefix that aids\n// debugging but carries no meaning.\n// ---------------------------------------------------------------------------\n\nconst ALPHABET = \"0123456789abcdefghijklmnopqrstuvwxyz\";\n\n/** Generate a new opaque id, e.g. `newId(\"scn\") -> \"scn_8f3kq2z1\"`. */\nexport function newId(prefix = \"\", length = 8): string {\n  // Rejection-sample so every alphabet character is equally likely: a plain\n  // `byte % 36` over-weights the first four characters.\n  const limit = 256 - (256 % ALPHABET.length); // 252\n  let token = \"\";\n  while (token.length < length) {\n    const bytes = new Uint8Array(length * 2);\n    globalThis.crypto.getRandomValues(bytes);\n    for (const b of bytes) {\n      if (b >= limit) continue;\n      token += ALPHABET[b % ALPHABET.length];\n      if (token.length === length) break;\n    }\n  }\n  return prefix ? `${prefix}_${token}` : token;\n}\n\n/** A url-ish slug from a human label; `\"project\"` when nothing usable is left. */\nexport function slug(name: string, fallback = \"project\"): string {\n  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\");\n  return s || fallback;\n}\n","// ---------------------------------------------------------------------------\n// FNV-1a, 32-bit.\n//\n// A published, fixed algorithm. Not cryptographic: it is for short stable\n// handles and change detection, where the properties that matter are that it is\n// the same everywhere and does not move between runs.\n// ---------------------------------------------------------------------------\n\n/** FNV-1a over a string's UTF-16 code units, as an unsigned 32-bit integer. */\nexport function fnv32(input: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n","// ---------------------------------------------------------------------------\n// Reading authored source files.\n// ---------------------------------------------------------------------------\n\nimport JSON5 from \"json5\";\n\n/**\n * Parse JSON5 source text. A leading byte-order mark is tolerated, because\n * editors on Windows add one and JSON5 will not accept it. Throws on malformed\n * input.\n */\nexport function parseSource(text: string): unknown {\n  const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n  return JSON5.parse(body);\n}\n","// ---------------------------------------------------------------------------\n// Find and replace over authored text.\n// ---------------------------------------------------------------------------\n\nexport interface FindOptions {\n  query: string;\n  caseSensitive?: boolean;\n  wholeWord?: boolean;\n}\n\n/**\n * Build the find matcher, or null for an empty query. Global, so every\n * occurrence in a string is replaced rather than only the first.\n *\n * The query is escaped: a person typing `a.b` means those three characters, not\n * \"a, anything, b\".\n */\nexport function findMatcher(opts: FindOptions): RegExp | null {\n  if (!opts.query) return null;\n  const esc = opts.query.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n  const body = opts.wholeWord ? `\\\\b${esc}\\\\b` : esc;\n  return new RegExp(body, opts.caseSensitive ? \"g\" : \"gi\");\n}\n\n// ---------------------------------------------------------------------------\n// Find by field value: the Field tab of both families' Find windows\n// (patterkit design/family-parity-2026-10.md item 16). Each app walks its own\n// project for the values (Storylets' card and outcome fields, Patter's\n// gameData) and asks these two what a query means, so `mood = tense` reads the\n// same in both.\n// ---------------------------------------------------------------------------\n\n/** A parsed Field query: a field, and optionally a value it must (`=`) or must\n *  not (`!=`) hold. With no `op` the query lists every value of the field. */\nexport interface FieldQuery {\n  /** As typed, folded to lower case: `mood`, or `extension.field`. */\n  field: string;\n  op?: \"=\" | \"!=\";\n  /** As typed, trimmed, one pair of surrounding quotes taken off. May be `\"\"`\n   *  (`mood =` asks for the field left empty). */\n  value?: string;\n}\n\n/**\n * `mood`, `mood = tense`, `mood != tense`, `ext.field = \"two words\"`. Null when\n * the text before the operator is not a field name (a letter or `_`, then\n * letters, digits, `_` or `-`; up to three of those joined by dots).\n */\nexport function parseFieldQuery(query: string): FieldQuery | null {\n  const m = /^\\s*([a-z_][\\w-]*(?:\\.[a-z_][\\w-]*){0,2})\\s*(?:(!=|=)\\s*(.*?))?\\s*$/i.exec(query);\n  if (!m) return null;\n  const field = m[1]!.toLowerCase();\n  if (m[2] === undefined) return { field };\n  let value = m[3]!;\n  const q = /^([\"'])(.*)\\1$/.exec(value);\n  if (q) value = q[2]!;\n  return { field, op: m[2] as \"=\" | \"!=\", value };\n}\n\n/** Does this field name answer the query's? Names compare without case. */\nexport const fieldNameMatches = (name: string, query: FieldQuery): boolean => name.toLowerCase() === query.field;\n\n/**\n * Does a field's value satisfy the query, read by its type (the family's list:\n * text, multiline, number, boolean, enum, flags, quality; `string` is text)?\n * Pass the value that HOLDS: the default when the node sets none, so\n * `mood = calm` finds the cards that leave a calm mood alone.\n *\n * - text, multiline, enum, quality, and any type this does not know: equal,\n *   ignoring case and the ends' whitespace\n * - flags: the list includes that flag (`= \"\"` is no flags set)\n * - number: numerically equal (`= 1.0` finds 1)\n * - boolean: `true` or `false`, ignoring case\n *\n * `!=` is the opposite of `=`. A query with no operator matches any value.\n */\nexport function fieldValueMatches(type: string, value: unknown, query: FieldQuery): boolean {\n  if (query.op === undefined || query.value === undefined) return true;\n  const holds = valueIs(type, value, query.value);\n  return query.op === \"=\" ? holds : !holds;\n}\n\nfunction valueIs(type: string, value: unknown, wanted: string): boolean {\n  const want = wanted.trim().toLowerCase();\n  if (type === \"flags\") {\n    const flags = Array.isArray(value) ? value.map((f) => String(f).toLowerCase()) : [];\n    return want === \"\" ? flags.length === 0 : flags.includes(want);\n  }\n  if (type === \"number\") {\n    if (want === \"\") return value === undefined || value === null || value === \"\";\n    const n = Number(want);\n    return !Number.isNaN(n) && typeof value === \"number\" && value === n;\n  }\n  if (type === \"boolean\") return (value === true && want === \"true\") || (value === false && want === \"false\");\n  return fieldValueText(type, value).trim().toLowerCase() === want;\n}\n\n/** A field's value as a row shows it: flags joined with commas, everything\n *  else as written, nothing for no value. */\nexport function fieldValueText(type: string, value: unknown): string {\n  if (value === undefined || value === null) return \"\";\n  if (type === \"flags\" && Array.isArray(value)) return value.join(\", \");\n  return typeof value === \"string\" ? value : JSON.stringify(value);\n}\n"]}

package/dist/index.d.cts

@@ -26,5 +26,41 @@ interface FindOptions {
  * "a, anything, b".
  */
 declare function findMatcher(opts: FindOptions): RegExp | null;
+/** A parsed Field query: a field, and optionally a value it must (`=`) or must
+ *  not (`!=`) hold. With no `op` the query lists every value of the field. */
+interface FieldQuery {
+    /** As typed, folded to lower case: `mood`, or `extension.field`. */
+    field: string;
+    op?: "=" | "!=";
+    /** As typed, trimmed, one pair of surrounding quotes taken off. May be `""`
+     *  (`mood =` asks for the field left empty). */
+    value?: string;
+}
+/**
+ * `mood`, `mood = tense`, `mood != tense`, `ext.field = "two words"`. Null when
+ * the text before the operator is not a field name (a letter or `_`, then
+ * letters, digits, `_` or `-`; up to three of those joined by dots).
+ */
+declare function parseFieldQuery(query: string): FieldQuery | null;
+/** Does this field name answer the query's? Names compare without case. */
+declare const fieldNameMatches: (name: string, query: FieldQuery) => boolean;
+/**
+ * Does a field's value satisfy the query, read by its type (the family's list:
+ * text, multiline, number, boolean, enum, flags, quality; `string` is text)?
+ * Pass the value that HOLDS: the default when the node sets none, so
+ * `mood = calm` finds the cards that leave a calm mood alone.
+ *
+ * - text, multiline, enum, quality, and any type this does not know: equal,
+ *   ignoring case and the ends' whitespace
+ * - flags: the list includes that flag (`= ""` is no flags set)
+ * - number: numerically equal (`= 1.0` finds 1)
+ * - boolean: `true` or `false`, ignoring case
+ *
+ * `!=` is the opposite of `=`. A query with no operator matches any value.
+ */
+declare function fieldValueMatches(type: string, value: unknown, query: FieldQuery): boolean;
+/** A field's value as a row shows it: flags joined with commas, everything
+ *  else as written, nothing for no value. */
+declare function fieldValueText(type: string, value: unknown): string;
 
-export { type FindOptions, findMatcher, fnv32, newId, parseSource, slug };
+export { type FieldQuery, type FindOptions, fieldNameMatches, fieldValueMatches, fieldValueText, findMatcher, fnv32, newId, parseFieldQuery, parseSource, slug };

package/dist/index.d.ts

@@ -26,5 +26,41 @@ interface FindOptions {
  * "a, anything, b".
  */
 declare function findMatcher(opts: FindOptions): RegExp | null;
+/** A parsed Field query: a field, and optionally a value it must (`=`) or must
+ *  not (`!=`) hold. With no `op` the query lists every value of the field. */
+interface FieldQuery {
+    /** As typed, folded to lower case: `mood`, or `extension.field`. */
+    field: string;
+    op?: "=" | "!=";
+    /** As typed, trimmed, one pair of surrounding quotes taken off. May be `""`
+     *  (`mood =` asks for the field left empty). */
+    value?: string;
+}
+/**
+ * `mood`, `mood = tense`, `mood != tense`, `ext.field = "two words"`. Null when
+ * the text before the operator is not a field name (a letter or `_`, then
+ * letters, digits, `_` or `-`; up to three of those joined by dots).
+ */
+declare function parseFieldQuery(query: string): FieldQuery | null;
+/** Does this field name answer the query's? Names compare without case. */
+declare const fieldNameMatches: (name: string, query: FieldQuery) => boolean;
+/**
+ * Does a field's value satisfy the query, read by its type (the family's list:
+ * text, multiline, number, boolean, enum, flags, quality; `string` is text)?
+ * Pass the value that HOLDS: the default when the node sets none, so
+ * `mood = calm` finds the cards that leave a calm mood alone.
+ *
+ * - text, multiline, enum, quality, and any type this does not know: equal,
+ *   ignoring case and the ends' whitespace
+ * - flags: the list includes that flag (`= ""` is no flags set)
+ * - number: numerically equal (`= 1.0` finds 1)
+ * - boolean: `true` or `false`, ignoring case
+ *
+ * `!=` is the opposite of `=`. A query with no operator matches any value.
+ */
+declare function fieldValueMatches(type: string, value: unknown, query: FieldQuery): boolean;
+/** A field's value as a row shows it: flags joined with commas, everything
+ *  else as written, nothing for no value. */
+declare function fieldValueText(type: string, value: unknown): string;
 
-export { type FindOptions, findMatcher, fnv32, newId, parseSource, slug };
+export { type FieldQuery, type FindOptions, fieldNameMatches, fieldValueMatches, fieldValueText, findMatcher, fnv32, newId, parseFieldQuery, parseSource, slug };

package/dist/index.js

@@ -38,7 +38,42 @@ function findMatcher(opts) {
   const body = opts.wholeWord ? `\\b${esc}\\b` : esc;
   return new RegExp(body, opts.caseSensitive ? "g" : "gi");
 }
+function parseFieldQuery(query) {
+  const m = /^\s*([a-z_][\w-]*(?:\.[a-z_][\w-]*){0,2})\s*(?:(!=|=)\s*(.*?))?\s*$/i.exec(query);
+  if (!m) return null;
+  const field = m[1].toLowerCase();
+  if (m[2] === void 0) return { field };
+  let value = m[3];
+  const q = /^(["'])(.*)\1$/.exec(value);
+  if (q) value = q[2];
+  return { field, op: m[2], value };
+}
+var fieldNameMatches = (name, query) => name.toLowerCase() === query.field;
+function fieldValueMatches(type, value, query) {
+  if (query.op === void 0 || query.value === void 0) return true;
+  const holds = valueIs(type, value, query.value);
+  return query.op === "=" ? holds : !holds;
+}
+function valueIs(type, value, wanted) {
+  const want = wanted.trim().toLowerCase();
+  if (type === "flags") {
+    const flags = Array.isArray(value) ? value.map((f) => String(f).toLowerCase()) : [];
+    return want === "" ? flags.length === 0 : flags.includes(want);
+  }
+  if (type === "number") {
+    if (want === "") return value === void 0 || value === null || value === "";
+    const n = Number(want);
+    return !Number.isNaN(n) && typeof value === "number" && value === n;
+  }
+  if (type === "boolean") return value === true && want === "true" || value === false && want === "false";
+  return fieldValueText(type, value).trim().toLowerCase() === want;
+}
+function fieldValueText(type, value) {
+  if (value === void 0 || value === null) return "";
+  if (type === "flags" && Array.isArray(value)) return value.join(", ");
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
 
-export { findMatcher, fnv32, newId, slug };
+export { fieldNameMatches, fieldValueMatches, fieldValueText, findMatcher, fnv32, newId, parseFieldQuery, slug };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ids.ts","../src/hash.ts","../src/find.ts"],"names":[],"mappings":";;;AASA,IAAM,QAAA,GAAW,sCAAA;AAGV,SAAS,KAAA,CAAM,MAAA,GAAS,EAAA,EAAI,MAAA,GAAS,CAAA,EAAW;AAGrD,EAAA,MAAM,KAAA,GAAQ,GAAA,GAAO,GAAA,GAAM,QAAA,CAAS,MAAA;AACpC,EAAA,IAAI,KAAA,GAAQ,EAAA;AACZ,EAAA,OAAO,KAAA,CAAM,SAAS,MAAA,EAAQ;AAC5B,IAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,MAAA,GAAS,CAAC,CAAA;AACvC,IAAA,UAAA,CAAW,MAAA,CAAO,gBAAgB,KAAK,CAAA;AACvC,IAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACrB,MAAA,IAAI,KAAK,KAAA,EAAO;AAChB,MAAA,KAAA,IAAS,QAAA,CAAS,CAAA,GAAI,QAAA,CAAS,MAAM,CAAA;AACrC,MAAA,IAAI,KAAA,CAAM,WAAW,MAAA,EAAQ;AAAA,IAC/B;AAAA,EACF;AACA,EAAA,OAAO,MAAA,GAAS,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,KAAK,CAAA,CAAA,GAAK,KAAA;AACzC;AAGO,SAAS,IAAA,CAAK,IAAA,EAAc,QAAA,GAAW,SAAA,EAAmB;AAC/D,EAAA,MAAM,CAAA,GAAI,IAAA,CAAK,IAAA,EAAK,CAAE,WAAA,EAAY,CAAE,OAAA,CAAQ,aAAA,EAAe,GAAG,CAAA,CAAE,OAAA,CAAQ,UAAA,EAAY,EAAE,CAAA;AACtF,EAAA,OAAO,CAAA,IAAK,QAAA;AACd;;;ACxBO,SAAS,MAAM,KAAA,EAAuB;AAC3C,EAAA,IAAI,CAAA,GAAI,UAAA;AACR,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,QAAQ,CAAA,EAAA,EAAK;AACrC,IAAA,CAAA,IAAK,KAAA,CAAM,WAAW,CAAC,CAAA;AACvB,IAAA,CAAA,GAAI,IAAA,CAAK,IAAA,CAAK,CAAA,EAAG,QAAU,CAAA;AAAA,EAC7B;AACA,EAAA,OAAO,CAAA,KAAM,CAAA;AACf;;;ACCO,SAAS,YAAY,IAAA,EAAkC;AAC5D,EAAA,IAAI,CAAC,IAAA,CAAK,KAAA,EAAO,OAAO,IAAA;AACxB,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,KAAA,CAAM,OAAA,CAAQ,uBAAuB,MAAM,CAAA;AAC5D,EAAA,MAAM,IAAA,GAAO,IAAA,CAAK,SAAA,GAAY,CAAA,GAAA,EAAM,GAAG,CAAA,GAAA,CAAA,GAAQ,GAAA;AAC/C,EAAA,OAAO,IAAI,MAAA,CAAO,IAAA,EAAM,IAAA,CAAK,aAAA,GAAgB,MAAM,IAAI,CAAA;AACzD","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Stable, immutable, opaque ids.\n//\n// Generated at creation, never derived from content or position, so an id\n// survives moving, renaming and reordering the thing it names. A short,\n// collision-resistant base-36 token with an optional type prefix that aids\n// debugging but carries no meaning.\n// ---------------------------------------------------------------------------\n\nconst ALPHABET = \"0123456789abcdefghijklmnopqrstuvwxyz\";\n\n/** Generate a new opaque id, e.g. `newId(\"scn\") -> \"scn_8f3kq2z1\"`. */\nexport function newId(prefix = \"\", length = 8): string {\n  // Rejection-sample so every alphabet character is equally likely: a plain\n  // `byte % 36` over-weights the first four characters.\n  const limit = 256 - (256 % ALPHABET.length); // 252\n  let token = \"\";\n  while (token.length < length) {\n    const bytes = new Uint8Array(length * 2);\n    globalThis.crypto.getRandomValues(bytes);\n    for (const b of bytes) {\n      if (b >= limit) continue;\n      token += ALPHABET[b % ALPHABET.length];\n      if (token.length === length) break;\n    }\n  }\n  return prefix ? `${prefix}_${token}` : token;\n}\n\n/** A url-ish slug from a human label; `\"project\"` when nothing usable is left. */\nexport function slug(name: string, fallback = \"project\"): string {\n  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\");\n  return s || fallback;\n}\n","// ---------------------------------------------------------------------------\n// FNV-1a, 32-bit.\n//\n// A published, fixed algorithm. Not cryptographic: it is for short stable\n// handles and change detection, where the properties that matter are that it is\n// the same everywhere and does not move between runs.\n// ---------------------------------------------------------------------------\n\n/** FNV-1a over a string's UTF-16 code units, as an unsigned 32-bit integer. */\nexport function fnv32(input: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n","// ---------------------------------------------------------------------------\n// Find and replace over authored text.\n// ---------------------------------------------------------------------------\n\nexport interface FindOptions {\n  query: string;\n  caseSensitive?: boolean;\n  wholeWord?: boolean;\n}\n\n/**\n * Build the find matcher, or null for an empty query. Global, so every\n * occurrence in a string is replaced rather than only the first.\n *\n * The query is escaped: a person typing `a.b` means those three characters, not\n * \"a, anything, b\".\n */\nexport function findMatcher(opts: FindOptions): RegExp | null {\n  if (!opts.query) return null;\n  const esc = opts.query.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n  const body = opts.wholeWord ? `\\\\b${esc}\\\\b` : esc;\n  return new RegExp(body, opts.caseSensitive ? \"g\" : \"gi\");\n}\n"]}
+{"version":3,"sources":["../src/ids.ts","../src/hash.ts","../src/find.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Stable, immutable, opaque ids.\n//\n// Generated at creation, never derived from content or position, so an id\n// survives moving, renaming and reordering the thing it names. A short,\n// collision-resistant base-36 token with an optional type prefix that aids\n// debugging but carries no meaning.\n// ---------------------------------------------------------------------------\n\nconst ALPHABET = \"0123456789abcdefghijklmnopqrstuvwxyz\";\n\n/** Generate a new opaque id, e.g. `newId(\"scn\") -> \"scn_8f3kq2z1\"`. */\nexport function newId(prefix = \"\", length = 8): string {\n  // Rejection-sample so every alphabet character is equally likely: a plain\n  // `byte % 36` over-weights the first four characters.\n  const limit = 256 - (256 % ALPHABET.length); // 252\n  let token = \"\";\n  while (token.length < length) {\n    const bytes = new Uint8Array(length * 2);\n    globalThis.crypto.getRandomValues(bytes);\n    for (const b of bytes) {\n      if (b >= limit) continue;\n      token += ALPHABET[b % ALPHABET.length];\n      if (token.length === length) break;\n    }\n  }\n  return prefix ? `${prefix}_${token}` : token;\n}\n\n/** A url-ish slug from a human label; `\"project\"` when nothing usable is left. */\nexport function slug(name: string, fallback = \"project\"): string {\n  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\");\n  return s || fallback;\n}\n","// ---------------------------------------------------------------------------\n// FNV-1a, 32-bit.\n//\n// A published, fixed algorithm. Not cryptographic: it is for short stable\n// handles and change detection, where the properties that matter are that it is\n// the same everywhere and does not move between runs.\n// ---------------------------------------------------------------------------\n\n/** FNV-1a over a string's UTF-16 code units, as an unsigned 32-bit integer. */\nexport function fnv32(input: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n","// ---------------------------------------------------------------------------\n// Find and replace over authored text.\n// ---------------------------------------------------------------------------\n\nexport interface FindOptions {\n  query: string;\n  caseSensitive?: boolean;\n  wholeWord?: boolean;\n}\n\n/**\n * Build the find matcher, or null for an empty query. Global, so every\n * occurrence in a string is replaced rather than only the first.\n *\n * The query is escaped: a person typing `a.b` means those three characters, not\n * \"a, anything, b\".\n */\nexport function findMatcher(opts: FindOptions): RegExp | null {\n  if (!opts.query) return null;\n  const esc = opts.query.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n  const body = opts.wholeWord ? `\\\\b${esc}\\\\b` : esc;\n  return new RegExp(body, opts.caseSensitive ? \"g\" : \"gi\");\n}\n\n// ---------------------------------------------------------------------------\n// Find by field value: the Field tab of both families' Find windows\n// (patterkit design/family-parity-2026-10.md item 16). Each app walks its own\n// project for the values (Storylets' card and outcome fields, Patter's\n// gameData) and asks these two what a query means, so `mood = tense` reads the\n// same in both.\n// ---------------------------------------------------------------------------\n\n/** A parsed Field query: a field, and optionally a value it must (`=`) or must\n *  not (`!=`) hold. With no `op` the query lists every value of the field. */\nexport interface FieldQuery {\n  /** As typed, folded to lower case: `mood`, or `extension.field`. */\n  field: string;\n  op?: \"=\" | \"!=\";\n  /** As typed, trimmed, one pair of surrounding quotes taken off. May be `\"\"`\n   *  (`mood =` asks for the field left empty). */\n  value?: string;\n}\n\n/**\n * `mood`, `mood = tense`, `mood != tense`, `ext.field = \"two words\"`. Null when\n * the text before the operator is not a field name (a letter or `_`, then\n * letters, digits, `_` or `-`; up to three of those joined by dots).\n */\nexport function parseFieldQuery(query: string): FieldQuery | null {\n  const m = /^\\s*([a-z_][\\w-]*(?:\\.[a-z_][\\w-]*){0,2})\\s*(?:(!=|=)\\s*(.*?))?\\s*$/i.exec(query);\n  if (!m) return null;\n  const field = m[1]!.toLowerCase();\n  if (m[2] === undefined) return { field };\n  let value = m[3]!;\n  const q = /^([\"'])(.*)\\1$/.exec(value);\n  if (q) value = q[2]!;\n  return { field, op: m[2] as \"=\" | \"!=\", value };\n}\n\n/** Does this field name answer the query's? Names compare without case. */\nexport const fieldNameMatches = (name: string, query: FieldQuery): boolean => name.toLowerCase() === query.field;\n\n/**\n * Does a field's value satisfy the query, read by its type (the family's list:\n * text, multiline, number, boolean, enum, flags, quality; `string` is text)?\n * Pass the value that HOLDS: the default when the node sets none, so\n * `mood = calm` finds the cards that leave a calm mood alone.\n *\n * - text, multiline, enum, quality, and any type this does not know: equal,\n *   ignoring case and the ends' whitespace\n * - flags: the list includes that flag (`= \"\"` is no flags set)\n * - number: numerically equal (`= 1.0` finds 1)\n * - boolean: `true` or `false`, ignoring case\n *\n * `!=` is the opposite of `=`. A query with no operator matches any value.\n */\nexport function fieldValueMatches(type: string, value: unknown, query: FieldQuery): boolean {\n  if (query.op === undefined || query.value === undefined) return true;\n  const holds = valueIs(type, value, query.value);\n  return query.op === \"=\" ? holds : !holds;\n}\n\nfunction valueIs(type: string, value: unknown, wanted: string): boolean {\n  const want = wanted.trim().toLowerCase();\n  if (type === \"flags\") {\n    const flags = Array.isArray(value) ? value.map((f) => String(f).toLowerCase()) : [];\n    return want === \"\" ? flags.length === 0 : flags.includes(want);\n  }\n  if (type === \"number\") {\n    if (want === \"\") return value === undefined || value === null || value === \"\";\n    const n = Number(want);\n    return !Number.isNaN(n) && typeof value === \"number\" && value === n;\n  }\n  if (type === \"boolean\") return (value === true && want === \"true\") || (value === false && want === \"false\");\n  return fieldValueText(type, value).trim().toLowerCase() === want;\n}\n\n/** A field's value as a row shows it: flags joined with commas, everything\n *  else as written, nothing for no value. */\nexport function fieldValueText(type: string, value: unknown): string {\n  if (value === undefined || value === null) return \"\";\n  if (type === \"flags\" && Array.isArray(value)) return value.join(\", \");\n  return typeof value === \"string\" ? value : JSON.stringify(value);\n}\n"]}

package/extensions.md

@@ -98,6 +98,7 @@ whose field has a type other than the claim's is an error naming where (the host
 | `flags` | A set of `values` | `[]` | As a set, value by value |
 | `quality` | One stage of `stages` (at least two, none empty, none twice) | The first stage | Three-way |
 | `reference` | The id of a node of the kind named by `to` | `""` | Three-way; validated to exist |
+| `pick` | One choice from the sources in `from` (below), as text, or `""` (automatic) | `""` | Three-way; validated against its sources |
 | `record` | Named `fields`, each a field declaration | Each field's default | Field by field |
 | `map` | Entries keyed by `key` (`{ type: "text" }` or `{ type: "reference", to }`), each of type `of` | `{}` | Key by key, then by the value's own type |
 | `list` with `id` | Records, each carrying the text field named by `id`, unique in the list | `[]` | Union by id, each item by its own type; order kept |
@@ -113,6 +114,32 @@ A value that does not fit is reported by `valueProblems`, through the kernel's `
 names no stage carries the stages either side of it as `options` (the kernel's `stagesEitherSide`, the whole
 ladder for a stage that is gone).
 
+### Picks
+
+A pick is a single choice whose choices come from sources the manifest names, in the order they're shown:
+
+```json5
+{ name: "to", type: "pick", from: [{ words: ["all"] }, { to: "cast" }, { list: "pointsOfInterest" }] }
+```
+
+- `words`: fixed words, named once each.
+- `to`: the nodes of a reference kind (the table above), held by id as a reference holds them.
+- `list`: a list of text (`{ type: "list", of: { type: "text" } }`, no `id`) on the extension's own `project`
+  target, by that field's name; the project node's value, else the field's default (`pickLists`).
+
+Empty is automatic: no word for it is stored, and an editor shows it as "auto". A pick isn't an `enum` whose values
+change: an enum's values are fixed and checked against the manifest, a pick's are the project's.
+
+`valueProblems` reports a value no source holds (`not-a-choice`, an error), given the host's nodes (`exists`) and
+lists (`list`) in its context; a source it can't see is not checked, so a value is reported missing only when every
+source can say. A value two sources hold is ambiguous (`pick-ambiguous`, a warning), and `pickClashes` reports each
+such name once for the project (`pick-clash`). `pickChoices` lists the choices, source by source, for an editor to
+draw.
+
+A host that renames a node of a `to` source rewrites the values naming it, as it rewrites references. A renamed
+entry of a project list isn't followed: a list of text can't tell a rename from a removal and an addition, so a value
+naming the old entry is reported missing.
+
 ### Stage renames
 
 An extension's ladder belongs to its manifest. A version that renames a stage says so on the field:
@@ -189,7 +216,7 @@ This covers every shard of a format, not only extension shards.
 ## Conformance
 
 `conformance/extensions/*.json` are the contract: hand-written cases for manifest validation, value validation,
-defaults, stage renames and the merge, with their expectations. `test/extensions.test.ts` runs them. A host that
+defaults, stage renames, picks and the merge, with their expectations. `test/extensions.test.ts` runs them. A host that
 reimplements any part runs the same files.
 
 This entry needs `@wildwinter/expr` and `@wildwinter/scoperegistry` (the kernel's value and ladder rules, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildwinter/toolkit",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Small shared pieces of the authoring tooling: opaque ids, a stable hash, JSON5 source parsing, find/replace matching, the archive guards, and (in ./extensions) the spec and merge for Patter extensions and Storylet extensions. Nothing here runs in a game.",
   "type": "module",
   "license": "MIT",