@m0saic/templates 0.2.0

package/LICENSE

@@ -0,0 +1,13 @@
+MIT License
+
+Copyright (c) 2026 m0saic LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+m0saic and the m0saic logo are trademarks of m0saic LLC.
+This license does not grant rights to use the m0saic name or logo
+in a way that implies endorsement.

package/README.md

@@ -0,0 +1,7 @@
+## License
+
+Templates in this repository are licensed under the MIT License.
+
+The m0saic DSL, template-utils, and types are licensed separately under Apache 2.0.
+
+The m0saic rendering engine and desktop application are proprietary and require a valid license for execution in production.

package/dist/freeze.d.ts

@@ -0,0 +1,406 @@
+/**
+ * ============================================================================
+ * FREEZE GATE — every template shipped in m0saic 0.2.0 is immutable
+ * ============================================================================
+ *
+ * `packages/templates` was cut for 0.2.0 on 2026-09-17 (release/0.2.0 = dev;
+ * the manifest was minted at the cut, founder ruling: hard lock at the cut,
+ * not at the tag — `tag` reads `v0.2.0 (pending …)` until npm publish). Someone
+ * out there holds the bytes: a shared `/make?t=…` link, a committed `.mosaic`,
+ * a rendered deliverable. A frozen template must not change meaning under
+ * them. Contract: the agent contract §10. (0.1.0 was withdrawn on 2026-09-14.)
+ *
+ * THE RULE. Comments only. Any behavioural change requires a new `vN+1/`
+ * folder beside the old one. Brand-new templates are not frozen at all —
+ * freedom is the default, the freeze is earned by shipping.
+ *
+ * ⭐ WHY `_shared/` IS IN SCOPE. Dozens of template files import from one of
+ * the eight `_shared/` directories. One edit to `alpine/_shared/alpine-theme.ts`
+ * moves every alpine template without touching a single `vN/` file, so a
+ * freeze that covered only version folders would be theatre. Shared helpers
+ * are frozen on the same terms; to change one, copy it into the new version's
+ * folder.
+ *
+ * ⭐ WHY THE FROZEN SET IS AN IMPORT CLOSURE. The same argument applies to a
+ * helper that happens to live OUTSIDE a `vN/` or `_shared/` folder — a pack's
+ * `utils/`, `internal/`, or a module at the pack root. At the 0.2.0 cut seven
+ * such files shaped shipped output (two of them even REGISTER shipped web
+ * ids), unfrozen. So {@link collectFrozenFiles} seeds the set with the
+ * `vN/` + `_shared/` rule and then follows every relative import (`./`, `../`)
+ * from a frozen file to any non-test `.ts` under `src/`, transitively. What a
+ * frozen template can reach is frozen. Pack barrels stay out — nothing frozen
+ * imports them — so a new template can still register itself.
+ *
+ * ⭐ WHY THE HASH KEEPS NEWLINES (hash v2). Automatic semicolon insertion
+ * makes a line break a TOKEN in JavaScript: `return path;` and
+ * `return\n    path;` are different programs (the second returns undefined).
+ * Hash v1 collapsed EVERY whitespace run — newlines included — to one space,
+ * so that edit to a frozen `_shared` helper hashed identically and slipped
+ * through (adversary 2026-09-17). v2 keeps a newline where the source had
+ * one, collapses horizontal whitespace, trims each line and folds blank lines:
+ * re-indentation and blank-line churn still hash alike; moving a token to the
+ * next line does not. The LINE TERMINATORS are the spec's four — LF, CR, and
+ * the Unicode LS (U+2028) / PS (U+2029): each ends a `//` comment, makes a
+ * block comment span lines, and is a line break for ASI, so the scanner treats
+ * them exactly like `\n` (a `// …<U+2028>evil()` would otherwise hash as a
+ * comment while Node executes `evil()`). `FREEZE_HASH_VERSION` rides in the
+ * manifest so a manifest minted under one hasher is refused by another
+ * OUTRIGHT rather than reported as "everything changed".
+ *
+ * ⭐ WHY THE MANIFEST ALSO PINS THE REGISTRY. Hashing frozen FILES cannot see
+ * a NEW file (not in the manifest) registering a shipped id with different
+ * defaults, or a pack barrel repointed at a different registering module
+ * while the original stays byte-identical. The registry now refuses a second
+ * first-party registration of an id (TEMPLATE_ID_ALREADY_REGISTERED) and
+ * records the registering module; the manifest's `registry` section pins,
+ * per shipped id, that file and a hash of the definition fields that decide
+ * shipped behaviour. check-registry Stage 0c holds the live registry to it.
+ *
+ * ⭐ WHY THE PIN ALSO COVERS THE RENDER BODY. The definition fields (defaults,
+ * schema, hints, flags) decide what `/make?t=<id>` renders — but so does the
+ * render function, and a registered template used to be mutable: an unfrozen
+ * file could reassign `getTemplate("<shipped id>").render` after registration
+ * with the file hash, the field pin and the gate all green (adversary
+ * 2026-09-17, bypass 3). The registry now deep-freezes every registration,
+ * and the pin covers the canonical source text (comments stripped, hash v2
+ * form) of the COMPILED `render` / `renderLite` / `renderCover` /
+ * `resolveOutputHints` — the dist functions the registry actually runs,
+ * reached through the wrapper link `defineMosaicTemplate` leaves
+ * (Symbol.for("m0saic.templateWrappedFrom")). Over compiled output,
+ * deliberately: it is deterministic for a build, and it means a TypeScript /
+ * tsconfig / template-utils change that alters the emitted body of a frozen
+ * render legitimately moves the pin and REQUIRES a re-mint at a release — that
+ * is the desired signal, not noise. Stage 0c says "redefined (render body)"
+ * when only the function text moved.
+ *
+ * ⭐ WHY THE WEB REGISTRY IS PINNED TOO. Mosaic Web bundles `src/web.ts`, not
+ * `src/index.ts`, and the two entries reach a template through different
+ * import paths (pack barrels, cherry-picked slugs, one `.web.ts` stand-in).
+ * A pin held only against the node registry would let a new unfrozen file
+ * register a shipped `web: true` id on the WEB side with different defaults
+ * — Stage 0 green (new file), 0b green (id still on web), 0c green (node
+ * untouched) — and every `/make?t=` link the 0.2.0 CLI prints would render
+ * something else. So a `web: true` pin is ALSO held against the registry the
+ * browser entry builds (loaded in a fresh child process, exactly as
+ * `gen-web-template-ids` does); where the web side legitimately differs from
+ * node at mint (`brand/community-m/v1` registers from `community-m.web.ts`),
+ * the pin records `webFile` / `webDefinitionSha256` beside the node values.
+ *
+ * ⭐ WHY THIS FILE HAS NO IMPORTS BEYOND NODE BUILTINS. `@m0saic/templates` is
+ * vendored into the published `m0saic` tarball, and `verifyStagedRequires` in
+ * scripts/build-publish-artifact.mjs scans every staged file for non-builtin
+ * `require(` / `from "…"`. Reaching for the TypeScript compiler here — the
+ * obvious way to strip comments — would put a `typescript` require inside the
+ * artifact and fail publish:audit, the same gate that proves `sharp` cannot
+ * reach it. Hence the hand-rolled scanner below.
+ */
+/** Committed at the package root; the diff IS the review of a freeze change. */
+export declare const FREEZE_MANIFEST_FILE = "frozen.manifest.json";
+/** Where frozen sources live, relative to the package root. */
+export declare const FROZEN_SRC_ROOT = "src/m0saic";
+/**
+ * Version of the canonical form `hashSource` produces. Recorded in the
+ * manifest at mint; `checkFreeze` refuses a manifest minted under a different
+ * version instead of comparing hashes that cannot match. Bump it whenever the
+ * canonical form changes (and re-mint at a release).
+ *
+ *   1 — comments stripped, every whitespace run (newlines too) → one space.
+ *   2 — newlines preserved as tokens (ASI), horizontal runs → one space,
+ *       lines trimmed, blank lines folded; LF / CR / U+2028 / U+2029 are all
+ *       line terminators. Manifests without the field are v1.
+ */
+export declare const FREEZE_HASH_VERSION = 2;
+/**
+ * What the manifest pins about one registered id. `file` is the registering
+ * module as a PACKAGE-relative source path (`src/m0saic/…/x.ts`, mapped back
+ * from the dist module that actually ran); `definitionSha256` is
+ * {@link definitionSha256} of the registered template (fields AND render
+ * bodies); `fieldsSha256` is {@link definitionFieldsSha256} (fields only —
+ * lets the gate say whether a moved pin was the data or the render body;
+ * absent on pins minted before render bodies joined, whose `definitionSha256`
+ * IS the fields-only hash); `web` marks ids the browser entry (`src/web.ts`)
+ * registered at mint — the shipped CLI prints `app.m0saic.io/make?t=<id>`
+ * links for those, so they may never leave web. `webFile` /
+ * `webDefinitionSha256` / `webFieldsSha256` are present ONLY when the browser
+ * entry registered the id from a different file or with a different
+ * definition than the node entry did at mint (a `.web.ts` stand-in); absent,
+ * the web side is held to the node values. Every pinned file (`file` and
+ * `webFile`) is itself in `files` — a pin over an unhashed module is not a pin.
+ */
+export type FreezeRegistryPin = {
+    file: string;
+    definitionSha256: string;
+    fieldsSha256?: string;
+    web?: boolean;
+    webFile?: string;
+    webDefinitionSha256?: string;
+    webFieldsSha256?: string;
+};
+export type FreezeManifest = {
+    release: string;
+    tag: string;
+    commit: string;
+    note: string;
+    /** {@link FREEZE_HASH_VERSION} the `files` hashes were minted with. Absent = 1. */
+    hashVersion?: number;
+    /** repo-relative path → canonical hash */
+    files: Record<string, string>;
+    /** template id → registration pin. Absent on manifests minted before 0.2.0's pins. */
+    registry?: Record<string, FreezeRegistryPin>;
+};
+export type FreezeReport = {
+    ok: boolean;
+    /**
+     * Set when the manifest was minted under a different hasher. Nothing else in
+     * the report is computed then: the hashes are incomparable, and "everything
+     * changed" would be a lie. Re-mint at a release.
+     */
+    hashVersionMismatch?: {
+        manifest: number;
+        checker: number;
+        message: string;
+    };
+    unchanged: string[];
+    /** Frozen files whose CODE changed — the violation this gate exists for. */
+    changed: string[];
+    /** Frozen files that no longer exist — removing shipped behaviour. */
+    deleted: string[];
+    /** Not in the manifest: new templates, free to change. */
+    unfrozen: string[];
+    /** Files the scanner could not confidently tokenize (hashed raw, strictly). */
+    lowConfidence: string[];
+};
+/**
+ * Strip comments, leaving string and template-literal interiors byte-for-byte
+ * intact.
+ *
+ * Whitespace BETWEEN tokens is collapsed, not removed — so `const a={x:1}`
+ * and `const a = { x: 1 }` hash DIFFERENTLY. That is deliberate: the rule is
+ * "comments only", and reformatting a frozen file is not a comment. Running a
+ * formatter over frozen sources SHOULD trip this gate.
+ *
+ * Newlines are kept (hash v2): a run of whitespace that contains a line break
+ * becomes exactly one `\n`, a run without one becomes one space, and a line
+ * never starts or ends with a space. So indentation and blank lines are free
+ * to change, while `return\n  path;` (which ASI reads as `return;`) hashes
+ * differently from `return path;`. A block comment that spans lines counts as
+ * a line break too — the spec treats it as a LineTerminator for ASI.
+ *
+ * "Line break" means every ECMAScript LineTerminator — LF, CR, U+2028 (LS)
+ * and U+2029 (PS). The last two are invisible in most editors, and each one
+ * ENDS a `//` comment and splits a block comment across lines for ASI, so a
+ * scanner that only knew `\n` would hash `// c<U+2028>evil()` as a comment
+ * while the engine runs `evil()`. Inside string and template literals they
+ * are copied verbatim like every other character (a raw LS in a template
+ * literal is a different value from a raw LF).
+ *
+ * Returns `confident: false` when the source ends inside a string, comment or
+ * regex — i.e. the scanner lost its place. Callers MUST then fall back to
+ * hashing the raw text: being over-strict (flagging a comment edit) is a safe
+ * failure for a freeze; being under-strict (missing a code edit) is not.
+ */
+export declare function stripComments(src: string): {
+    text: string;
+    confident: boolean;
+};
+/**
+ * sha256 of the canonical (comment- and format-insensitive) form.
+ *
+ * ⭐ LINE ENDINGS ARE NORMALIZED FIRST. A Windows clone (core.autocrlf=true)
+ * checks sources out as CRLF. `stripComments` collapses `\r` between tokens,
+ * but copies template-literal interiors verbatim — so every multi-line template
+ * literal would hash differently on Windows and trip the gate on untouched
+ * files. Normalizing is not a loosening: JS itself turns CRLF/CR inside a
+ * template literal into LF, so the two checkouts are the same program. Escaped
+ * `\r` (a backslash in the source) is untouched and still hashes as code.
+ */
+export declare function hashSource(src: string): {
+    hash: string;
+    confident: boolean;
+};
+/** The hasher version a manifest was minted with (absent field = v1). */
+export declare function manifestHashVersion(manifest: Pick<FreezeManifest, "hashVersion">): number;
+/**
+ * One line for every gate to print when the versions differ. The fix depends
+ * on the DIRECTION: a manifest OLDER than the checker needs a release re-mint;
+ * a manifest NEWER than the checker means this clone's `dist/freeze.js` is a
+ * stale build (branch switched, never rebuilt) — rebuild, never re-mint.
+ */
+export declare function describeHashVersionMismatch(manifestVersion: number): string;
+/**
+ * The template DATA fields whose values decide what a shipped id RENDERS at
+ * its defaults and how a host treats it. Browse metadata (label, description,
+ * tags, preview) is left out on purpose: it changes what a gallery shows, not
+ * what `/make?t=<id>` produces — and it lives in the frozen file anyway. The
+ * render functions are pinned beside these — see {@link RENDER_PIN_FIELDS}.
+ */
+export declare const DEFINITION_PIN_FIELDS: readonly ["version", "capabilities", "role", "primitive", "internal", "deprecated", "aspectRatio", "outputHints", "lattice", "defaultFinalizeOpts", "skipAutoCompact", "propsSchema", "defaultProps", "outputsSchema", "upstreamVariablesSchema", "upstreamDataSchema", "sidecarsSchema", "defaultOutputs"];
+/**
+ * Deterministic JSON: object keys sorted at every depth, arrays in order,
+ * `undefined` members dropped (like JSON.stringify), functions rendered as
+ * "[Function]" (a schema's `validate` callback is code, and code is what the
+ * FILE hash guards), non-finite numbers as null.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * The template functions whose COMPILED source text the pin covers — what a
+ * shipped id actually runs, plus `resolveOutputHints`, which hosts call before
+ * rendering to seed the canvas (width / height / fps / duration / format) from
+ * the props. `renderTutorial` is left out: it is "?"-panel material, never a
+ * `/make` output.
+ */
+export declare const RENDER_PIN_FIELDS: readonly ["render", "renderLite", "renderCover", "resolveOutputHints"];
+/**
+ * The link `defineMosaicTemplate` leaves on each wrapper function, pointing at
+ * the function it wraps (`TEMPLATE_WRAPPED_FROM` in template-utils). Named by
+ * `Symbol.for` so this file needs no import to follow it.
+ */
+export declare const TEMPLATE_WRAPPED_FROM_KEY: unique symbol;
+/**
+ * Canonical source text of a template function: the innermost function under
+ * the wrapper chain, `toString()`-ed, in the hash-v2 canonical form (comments
+ * stripped, horizontal whitespace collapsed, newlines kept) — so a comment-only
+ * edit to a frozen file moves neither the file hash nor the pin. `undefined`
+ * for a non-function (an absent `renderLite`).
+ */
+export declare function renderSourceText(fn: unknown): string | undefined;
+/** sha256 of the canonical JSON of a template's {@link DEFINITION_PIN_FIELDS} alone (no render bodies). */
+export declare function definitionFieldsSha256(template: Record<string, unknown>): string;
+/**
+ * sha256 of the canonical JSON of a template's {@link DEFINITION_PIN_FIELDS}
+ * plus the canonical source text of its {@link RENDER_PIN_FIELDS} — the
+ * whole of what decides what a shipped id renders. See the header on why the
+ * render bodies are pinned over COMPILED output.
+ */
+export declare function definitionSha256(template: Record<string, unknown>): string;
+/**
+ * Map a registering module (as `getTemplateMeta().registeredFrom` reports it:
+ * repo-relative `packages/templates/dist/…/x.js`, or absolute) to the
+ * package-relative SOURCE path the pin stores (`src/…/x.ts`). Anything not
+ * under this package's dist/src is returned as given — it still pins.
+ */
+export declare function registeringSourcePath(packageRoot: string, registeredFrom: string): string;
+/** One live registration, as check-registry gathers it from the registry.
+ *  `fieldsSha256` (fields only) lets a moved pin be told apart: data or render body. */
+export type LiveRegistration = {
+    id: string;
+    file: string;
+    definitionSha256: string;
+    fieldsSha256?: string;
+};
+/** Gather one live registration from a registered template and its registering source file. */
+export declare function liveRegistrationOf(id: string, file: string, template: Record<string, unknown>): LiveRegistration;
+/** Why a pinned id reads as redefined: its data fields moved, or only a render body did. */
+export type RedefinedReason = "fields" | "render body";
+export type RegistryPinReport = {
+    ok: boolean;
+    /** Pins the manifest carries. 0 → the manifest predates pins (nothing to hold). */
+    pinned: number;
+    held: string[];
+    /** Pinned ids no longer registered at all. */
+    missing: {
+        id: string;
+        file: string;
+    }[];
+    /** Pinned ids now registered from a different file. */
+    moved: {
+        id: string;
+        pinnedFile: string;
+        file: string;
+    }[];
+    /** Pinned ids whose definition hashes differently — `reason` says whether the
+     *  data fields moved or only a render body did (see {@link RedefinedReason}). */
+    redefined: {
+        id: string;
+        file: string;
+        reason: RedefinedReason;
+    }[];
+    /** Registered but not pinned: new work, free. */
+    unpinned: string[];
+};
+/** Hold the live registry to the manifest's pins (Stage 0c). */
+export declare function checkRegistryPins(manifest: Pick<FreezeManifest, "registry">, live: readonly LiveRegistration[]): RegistryPinReport;
+/** Ids the manifest pinned as being on web at mint (sorted). */
+export declare function pinnedWebIds(manifest: Pick<FreezeManifest, "registry">): string[];
+/**
+ * The `web: true` pins as the BROWSER registry must satisfy them: the web
+ * values where the mint recorded a divergence, the node values otherwise.
+ * Feed the result to {@link checkRegistryPins} together with the live
+ * registrations of `src/web.ts` (gathered in a fresh process — see
+ * check-registry Stage 0c). Ids the web entry added since the mint show up
+ * as `unpinned` there: new work.
+ */
+export declare function webRegistryPins(manifest: Pick<FreezeManifest, "registry">): Pick<FreezeManifest, "registry">;
+/**
+ * Pins whose registering file is NOT itself in `files`. A pin over an unhashed
+ * module holds the definition but not the code it runs — at the 0.2.0 cut two
+ * shipped web ids registered from helpers outside every `vN/` folder. The
+ * import closure freezes them now; this is the invariant that keeps it so.
+ * `(unknown)` provenance (no usable stack frame) counts as unfrozen.
+ */
+export declare function unfrozenPinFiles(manifest: Pick<FreezeManifest, "files" | "registry">): {
+    id: string;
+    file: string;
+}[];
+/**
+ * A path is a frozen SEED when it is a non-test `.ts` under `src/m0saic/` that
+ * sits in a version folder (`…/v3/…`) or a shared folder (`…/_shared/…`).
+ * The full frozen set is the relative-import closure of the seeds — see
+ * {@link collectFrozenFiles}; a file reached that way is frozen although this
+ * predicate says false for it, so the gate and the hook ask the MANIFEST
+ * (`files[rel] !== undefined`), never this predicate alone, whether a path is
+ * held. This predicate decides what is NEW WORK: a seed-shaped path absent
+ * from the manifest.
+ *
+ * Deliberately NOT seeds: `*.test.ts` (adding tests to a frozen template is
+ * the one way to improve it without moving it), `*.d.ts`, and the PACK-level
+ * barrels (`src/m0saic/<pack>/index.ts`) — a new template has to register
+ * itself. Barrels inside a version folder ARE frozen. (`gen-*.ts` tooling
+ * inside a version folder is a seed like any other file there.)
+ */
+export declare function isFrozenPath(relPath: string): boolean;
+/**
+ * Relative module specifiers (`./x`, `../x`) a source file imports, read off
+ * its comment-stripped text so a commented-out import is not a dependency.
+ * Covers `import … from`, bare `import "…"`, `export … from`, `import("…")`
+ * and `require("…")`. Package imports (`@m0saic/…`) are not returned — those
+ * are Tier 2 by the launch plan, vendored beside this package.
+ */
+export declare function relativeImportSpecifiers(src: string): string[];
+/**
+ * Every currently-frozen file, package-relative and sorted: the
+ * {@link isFrozenPath} seeds plus every freezable `.ts` under `src/` they
+ * reach through relative imports, transitively. What a frozen template can
+ * run is frozen — a helper in `utils/` or at a pack root is shipped behaviour
+ * exactly as a `_shared/` one is (see the header).
+ */
+export declare function collectFrozenFiles(packageRoot: string): string[];
+export declare function readFreezeManifest(packageRoot: string): FreezeManifest | null;
+/**
+ * Compare the working tree against the committed manifest.
+ * `changed` and `deleted` are build errors; `unfrozen` is new work.
+ */
+export declare function checkFreeze(packageRoot: string, manifest: FreezeManifest): FreezeReport;
+/**
+ * Mint a manifest from the current tree — the deliberate act at a release.
+ * `registry` is every live registration of the NODE entry (the caller loads
+ * the registry; this file stays free of it), which ids the browser entry
+ * registered, and — when given — the browser entry's own live registrations
+ * (`webLive`, gathered in a fresh process): a `web: true` pin records
+ * `webFile` / `webDefinitionSha256` / `webFieldsSha256` only where the web
+ * side differs from node.
+ *
+ * Throws when a pin would name a file the manifest does not hash (an
+ * `(unknown)` provenance, or a registering module outside the frozen set):
+ * a pin over unhashed code is not a lock, and a mint must never produce one.
+ */
+export declare function mintFreezeManifest(packageRoot: string, meta: {
+    release: string;
+    tag: string;
+    commit: string;
+    note: string;
+}, registry?: {
+    live: readonly LiveRegistration[];
+    webIds?: readonly string[];
+    webLive?: readonly LiveRegistration[];
+}): FreezeManifest;