@shop-on/theme-contract 0.0.0-stage → 0.2.0

package/dist/LICENSE.md

@@ -0,0 +1,39 @@
+# Cody Theme Development License
+
+Copyright (c) 2026 Cody LLC. All rights reserved except as granted below.
+
+"The Software" is this package, its source, and its documentation. "The
+Platform" is Cody, the commerce platform operated by Cody LLC.
+
+## 1. Grant
+
+You may use, copy and modify the Software, and distribute modified copies, solely
+to develop, test, and distribute themes, apps and other extensions that run on
+the Platform.
+
+## 2. Restrictions
+
+You may not:
+
+1. use the Software, or anything derived from it, with any commerce platform,
+   storefront or hosting service other than the Platform;
+2. use the Software to build a product that competes with the Platform;
+3. sublicense the Software, or distribute it other than as part of a theme,
+   app or extension for the Platform;
+4. remove or alter this license or any copyright notice in the Software.
+
+## 3. Your work
+
+Themes, apps and extensions you build with the Software are yours. The parts of
+the Software they include stay under this license.
+
+## 4. Termination
+
+This license ends automatically if you break any of its terms. You must then
+stop using the Software and delete your copies of it.
+
+## 5. No warranty
+
+The Software is provided "as is", without warranty of any kind. Cody LLC is not
+liable for any claim, damages or other liability arising from the Software or
+its use.

package/dist/block-path.d.ts

@@ -0,0 +1,32 @@
+//#region src/block-path.d.ts
+export declare const BLOCK_PATH_SEPARATOR = ".";
+export declare function joinBlockPath(path: readonly string[]): string;
+export declare function splitBlockPath(value: string | null | undefined): string[];
+export declare function blockPathsEqual(a: readonly string[] | undefined, b: readonly string[] | undefined): boolean;
+/** True when `prefix` names `path` itself or one of its ancestors. */
+export declare function isBlockPathPrefix(prefix: readonly string[], path: readonly string[]): boolean;
+/**
+ * Coerce an untrusted wire value into a block path. Accepts the modern
+ * `string[]` and dotted-`string` forms, plus the legacy single
+ * `parentBlockId` (normalized to a one-segment path) that older bundled
+ * theme-react bridges still emit. Anything else yields `[]`.
+ */
+export declare function normalizeBlockPath(value: unknown, legacyParentBlockId?: unknown): string[];
+/** The block type a container's `blocks` map holds — recovered from the
+ * section/block type the caller passed, so the resolved container keeps its
+ * real type (`type`, `settings`, `custom_css`, …) instead of a structural
+ * stand-in. */
+type BlocksOf<S> = S extends {
+  blocks?: Record<string, infer B> | undefined;
+} ? B : never;
+/**
+ * Walk `path` hop by hop from the section and return the container it names —
+ * the section itself for an empty path, otherwise the block at the end of the
+ * chain. Returns `undefined` the instant a hop is missing, so callers can fail
+ * loudly (`container_not_found`) instead of silently writing nowhere.
+ */
+export declare function resolveContainerAtPath<S extends {
+  blocks?: Record<string, unknown>;
+}>(section: S | undefined, path: readonly string[]): S | BlocksOf<S> | undefined;
+//#endregion
+export {};

package/dist/block-path.js

@@ -0,0 +1,52 @@
+//#region src/block-path.ts
+const BLOCK_PATH_SEPARATOR = ".";
+function joinBlockPath(path) {
+	return path.join(".");
+}
+function splitBlockPath(value) {
+	if (!value) return [];
+	return value.split(".").filter((seg) => seg !== "");
+}
+function blockPathsEqual(a, b) {
+	const left = a ?? [];
+	const right = b ?? [];
+	if (left.length !== right.length) return false;
+	for (let i = 0; i < left.length; i++) if (left[i] !== right[i]) return false;
+	return true;
+}
+/** True when `prefix` names `path` itself or one of its ancestors. */
+function isBlockPathPrefix(prefix, path) {
+	if (prefix.length > path.length) return false;
+	for (let i = 0; i < prefix.length; i++) if (prefix[i] !== path[i]) return false;
+	return true;
+}
+/**
+* Coerce an untrusted wire value into a block path. Accepts the modern
+* `string[]` and dotted-`string` forms, plus the legacy single
+* `parentBlockId` (normalized to a one-segment path) that older bundled
+* theme-react bridges still emit. Anything else yields `[]`.
+*/
+function normalizeBlockPath(value, legacyParentBlockId) {
+	if (Array.isArray(value)) return value.filter((seg) => typeof seg === "string" && seg !== "");
+	if (typeof value === "string") return splitBlockPath(value);
+	if (typeof legacyParentBlockId === "string" && legacyParentBlockId !== "") return [legacyParentBlockId];
+	return [];
+}
+/**
+* Walk `path` hop by hop from the section and return the container it names —
+* the section itself for an empty path, otherwise the block at the end of the
+* chain. Returns `undefined` the instant a hop is missing, so callers can fail
+* loudly (`container_not_found`) instead of silently writing nowhere.
+*/
+function resolveContainerAtPath(section, path) {
+	if (!section) return void 0;
+	if (path.length === 0) return section;
+	let node = section.blocks?.[path[0]];
+	for (let i = 1; i < path.length; i++) {
+		if (!node) return void 0;
+		node = node.blocks?.[path[i]];
+	}
+	return node;
+}
+//#endregion
+export { BLOCK_PATH_SEPARATOR, blockPathsEqual, isBlockPathPrefix, joinBlockPath, normalizeBlockPath, resolveContainerAtPath, splitBlockPath };

package/dist/color-palette.d.ts

@@ -0,0 +1,48 @@
+//#region src/color-palette.d.ts
+export declare const PALETTE_GROUP_TYPE = "color_palette_group";
+export declare const PALETTE_PREFIX = "color_palette.";
+export declare const PALETTE_REF_PREFIX = "palette:";
+/** Shopify's bounds: a palette holds at least 2 and at most 20 colors. */
+export declare const MIN_PALETTE_COLORS = 2;
+export declare const MAX_PALETTE_COLORS = 20;
+/** Substituted when a `palette:` ref points at a color that no longer exists
+ * (hand-edited JSON, a half-applied migration). Mid-gray keeps the surface
+ * legible; leaving the raw ref in place would emit invalid CSS and blank the
+ * declaration unpredictably. */
+export declare const PALETTE_FALLBACK_COLOR = "#808080";
+export interface PaletteColor {
+  id: string;
+  label: string;
+  value: string;
+}
+export declare function paletteKey(id: string, field: "label" | "value"): string;
+export declare function paletteRef(id: string): string;
+/** `"palette:brand"` → `"brand"`. Anything else (including a hex literal, a
+ * non-string, or a ref with an unsafe id) → `null`. */
+export declare function parsePaletteRef(value: unknown): string | null;
+export declare function comparePaletteIds(a: string, b: string): number;
+/** Every palette color defined in a flat theme-settings map, ordered
+ * `palette_1`, `palette_2`, … then any non-numeric ids alphabetically. */
+export declare function parsePalette(settings: Record<string, unknown>): PaletteColor[];
+/** Palette id → literal color, the lookup table every resolver takes. */
+export declare function paletteValues(settings: Record<string, unknown>): Record<string, string>;
+/** A single value: `palette:<id>` → its literal (or the neutral fallback);
+ * everything else passes through untouched. */
+export declare function resolvePaletteValue(value: unknown, palette: Record<string, string>): unknown;
+/**
+ * Replace every `palette:<id>` ref inside a template / section-group document
+ * (section settings, block settings, nested block settings) with its literal
+ * color. Structurally shared: untouched branches keep their identity, and a
+ * document with no refs is returned as-is.
+ */
+export declare function resolvePaletteRefs<T>(document: T, palette: Record<string, string>): T;
+/** Cheap pre-check so callers can skip loading the palette (and, in the loader,
+ * an extra settings fetch) for the overwhelmingly common ref-free document. */
+export declare function hasPaletteRefs(node: unknown): boolean;
+/**
+ * The flat theme-settings map resolves against ITSELF — palette definitions and
+ * the settings that reference them live in the same document. `color_palette.*`
+ * keys are skipped so a definition can never chain into another definition.
+ */
+export declare function resolveThemeSettingsPalette(settings: Record<string, unknown>): Record<string, unknown>;
+//#endregion

package/dist/color-palette.js

@@ -0,0 +1,143 @@
+//#region src/color-palette.ts
+const PALETTE_GROUP_TYPE = "color_palette_group";
+const PALETTE_PREFIX = "color_palette.";
+const PALETTE_REF_PREFIX = "palette:";
+/** Shopify's bounds: a palette holds at least 2 and at most 20 colors. */
+const MIN_PALETTE_COLORS = 2;
+const MAX_PALETTE_COLORS = 20;
+/** Substituted when a `palette:` ref points at a color that no longer exists
+* (hand-edited JSON, a half-applied migration). Mid-gray keeps the surface
+* legible; leaving the raw ref in place would emit invalid CSS and blank the
+* declaration unpredictably. */
+const PALETTE_FALLBACK_COLOR = "#808080";
+const PALETTE_ID_RE = /^[a-zA-Z0-9_-]+$/;
+const NUMERIC_SUFFIX_RE = /^palette_(\d+)$/;
+function paletteKey(id, field) {
+	return `${PALETTE_PREFIX}${id}.${field}`;
+}
+function paletteRef(id) {
+	return `${PALETTE_REF_PREFIX}${id}`;
+}
+/** `"palette:brand"` → `"brand"`. Anything else (including a hex literal, a
+* non-string, or a ref with an unsafe id) → `null`. */
+function parsePaletteRef(value) {
+	if (typeof value !== "string" || !value.startsWith("palette:")) return null;
+	const id = value.slice(8);
+	return PALETTE_ID_RE.test(id) ? id : null;
+}
+function comparePaletteIds(a, b) {
+	const ma = a.match(NUMERIC_SUFFIX_RE);
+	const mb = b.match(NUMERIC_SUFFIX_RE);
+	if (ma && mb) return Number.parseInt(ma[1], 10) - Number.parseInt(mb[1], 10);
+	if (ma) return -1;
+	if (mb) return 1;
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Every palette color defined in a flat theme-settings map, ordered
+* `palette_1`, `palette_2`, … then any non-numeric ids alphabetically. */
+function parsePalette(settings) {
+	const byId = {};
+	for (const [key, raw] of Object.entries(settings)) {
+		if (!key.startsWith("color_palette.") || typeof raw !== "string") continue;
+		const rest = key.slice(14);
+		const dot = rest.indexOf(".");
+		if (dot === -1) continue;
+		const id = rest.slice(0, dot);
+		const field = rest.slice(dot + 1);
+		if (!PALETTE_ID_RE.test(id)) continue;
+		if (field !== "label" && field !== "value") continue;
+		(byId[id] ??= {})[field] = raw;
+	}
+	return Object.entries(byId).filter(([, parts]) => typeof parts.value === "string").map(([id, parts]) => ({
+		id,
+		label: parts.label || id,
+		value: parts.value
+	})).sort((a, b) => comparePaletteIds(a.id, b.id));
+}
+/** Palette id → literal color, the lookup table every resolver takes. */
+function paletteValues(settings) {
+	const out = {};
+	for (const color of parsePalette(settings)) out[color.id] = color.value;
+	return out;
+}
+/** A single value: `palette:<id>` → its literal (or the neutral fallback);
+* everything else passes through untouched. */
+function resolvePaletteValue(value, palette) {
+	const id = parsePaletteRef(value);
+	if (id === null) return value;
+	return palette[id] ?? "#808080";
+}
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function resolveSettingsMap(settings, palette) {
+	let changed = false;
+	const out = {};
+	for (const [key, value] of Object.entries(settings)) {
+		const next = resolvePaletteValue(value, palette);
+		if (next !== value) changed = true;
+		out[key] = next;
+	}
+	return changed ? out : settings;
+}
+function resolveNode(node, palette) {
+	if (Array.isArray(node)) {
+		let changed = false;
+		const out = node.map((item) => {
+			const next = resolveNode(item, palette);
+			if (next !== item) changed = true;
+			return next;
+		});
+		return changed ? out : node;
+	}
+	if (!isPlainObject(node)) return node;
+	let changed = false;
+	const out = {};
+	for (const [key, value] of Object.entries(node)) {
+		const next = key === "settings" && isPlainObject(value) ? resolveSettingsMap(value, palette) : resolveNode(value, palette);
+		if (next !== value) changed = true;
+		out[key] = next;
+	}
+	return changed ? out : node;
+}
+/**
+* Replace every `palette:<id>` ref inside a template / section-group document
+* (section settings, block settings, nested block settings) with its literal
+* color. Structurally shared: untouched branches keep their identity, and a
+* document with no refs is returned as-is.
+*/
+function resolvePaletteRefs(document, palette) {
+	return resolveNode(document, palette);
+}
+/** Cheap pre-check so callers can skip loading the palette (and, in the loader,
+* an extra settings fetch) for the overwhelmingly common ref-free document. */
+function hasPaletteRefs(node) {
+	if (Array.isArray(node)) return node.some((item) => hasPaletteRefs(item));
+	if (!isPlainObject(node)) return false;
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "settings" && isPlainObject(value)) {
+			for (const inner of Object.values(value)) if (parsePaletteRef(inner) !== null) return true;
+			continue;
+		}
+		if (hasPaletteRefs(value)) return true;
+	}
+	return false;
+}
+/**
+* The flat theme-settings map resolves against ITSELF — palette definitions and
+* the settings that reference them live in the same document. `color_palette.*`
+* keys are skipped so a definition can never chain into another definition.
+*/
+function resolveThemeSettingsPalette(settings) {
+	const palette = paletteValues(settings);
+	let changed = false;
+	const out = {};
+	for (const [key, value] of Object.entries(settings)) {
+		const next = key.startsWith("color_palette.") ? value : resolvePaletteValue(value, palette);
+		if (next !== value) changed = true;
+		out[key] = next;
+	}
+	return changed ? out : settings;
+}
+//#endregion
+export { MAX_PALETTE_COLORS, MIN_PALETTE_COLORS, PALETTE_FALLBACK_COLOR, PALETTE_GROUP_TYPE, PALETTE_PREFIX, PALETTE_REF_PREFIX, comparePaletteIds, hasPaletteRefs, paletteKey, paletteRef, paletteValues, parsePalette, parsePaletteRef, resolvePaletteRefs, resolvePaletteValue, resolveThemeSettingsPalette };

package/dist/document.d.ts

@@ -0,0 +1,115 @@
+import { BlockDefinition, SchemaSetting, TemplateBlock, TemplateSection } from "./schemas.js";
+//#region src/document.d.ts
+export interface SelectedSection {
+  instanceId: string;
+  section: TemplateSection;
+  blocks: TemplateBlock[];
+  staticBlocks: Record<string, TemplateBlock>;
+}
+export interface TemplateShape {
+  layout?: string;
+  sections: Record<string, TemplateSection>;
+  order: string[];
+  section_groups?: Record<string, {
+    sections: Record<string, TemplateSection>;
+    order: string[];
+  }>;
+}
+export interface CollectedTypes {
+  sections: Set<string>;
+  blocks: Set<string>;
+  layouts: Set<string>;
+}
+export declare function defaultSettings(schemaDefs?: SchemaSetting[]): Record<string, unknown>;
+export declare function staticChildId(childType: string, parentType: string): string;
+export declare function staticBlockId(type: string): string;
+export declare function buildStaticChildren(args: {
+  parentType: string;
+  childDefs: BlockDefinition[];
+  getBlockSchema: (type: string) => {
+    settings?: SchemaSetting[];
+    blocks?: BlockDefinition[];
+  } | undefined;
+}): {
+  blocks: Record<string, TemplateBlock>;
+  block_order: string[];
+};
+type BlockSchemaLike = {
+  settings?: SchemaSetting[];
+  blocks?: BlockDefinition[];
+} | undefined;
+/**
+ * Build a fresh block instance the way a merchant adding it should get it:
+ * schema defaults → its schema's static children → its first preset overlaid.
+ * The preset is Horizon's block `presets[0]` — the one Shopify applies when a
+ * block is added — so a container arrives with the content it ships with (an
+ * accordion with its rows, a recommendations block with its heading and card
+ * fields) rather than as an empty frame. Same inputs contract as
+ * `buildSectionInstance`: schemas already t:-resolved, `idFor` injected.
+ */
+export declare function buildBlockInstance(args: {
+  type: string;
+  getBlockSchema: (type: string) => BlockSchemaLike;
+  preset?: {
+    settings?: Record<string, unknown>;
+    blocks?: BlockDefinition[];
+  };
+  idFor: (type: string) => string;
+}): TemplateBlock;
+/**
+ * Build a fresh section instance from its schema: schema/preset defaults →
+ * seeded static blocks → preset overlay. Shared by the admin editor's
+ * `addSection` and the storefront's standalone section-preview route so both
+ * produce identical instances.
+ *
+ * Inputs must be **already t:-resolved** — the admin gets resolved schemas from
+ * the orchestrator's editor-loader; the storefront resolves on-disk before
+ * calling. `idFor` is injected (admin mints a random suffix; the preview route
+ * uses a deterministic counter) so callers control id stability.
+ */
+export declare function buildSectionInstance(args: {
+  type: string;
+  sectionSchema: {
+    settings?: SchemaSetting[];
+    blocks?: BlockDefinition[];
+  } | undefined;
+  getBlockSchema: (type: string) => BlockSchemaLike;
+  preset?: {
+    settings?: Record<string, unknown>;
+    blocks?: BlockDefinition[];
+  };
+  idFor: (type: string) => string;
+}): TemplateSection & {
+  blocks: Record<string, TemplateBlock>;
+  block_order: string[];
+};
+export declare function selectRenderableSections(sections: Record<string, TemplateSection>, order: string[]): SelectedSection[];
+export declare function selectRenderableChildren(block: TemplateBlock): TemplateBlock[];
+export declare function collectTypes(template: TemplateShape): CollectedTypes;
+type BlockNode = {
+  static?: boolean;
+  blocks?: Record<string, BlockNode>;
+  block_order?: string[];
+} & Record<string, unknown>;
+type BlockContainer = {
+  blocks?: Record<string, BlockNode>;
+  block_order?: string[];
+} & Record<string, unknown>;
+export declare function stripStaticFromBlockOrder(container: BlockContainer): number;
+export type SeedMissingStaticsReport = {
+  added: Array<{
+    sectionId: string;
+    blockPath: string;
+  }>;
+  reordered: Array<{
+    sectionId: string;
+    containerPath: string;
+  }>;
+};
+export declare function seedMissingStatics(oldTemplate: {
+  sections: Record<string, TemplateSection>;
+}, freshTemplate: {
+  sections: Record<string, TemplateSection>;
+}): SeedMissingStaticsReport;
+//#endregion
+export {};