@feeef.dev/cli 0.2.0

package/scaffolds/blank/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "feeef-theme",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Feeef Lithium theme",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "feeef template build",
+    "check": "feeef template check",
+    "dev": "feeef template dev",
+    "publish": "feeef template publish",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.4.5"
+  }
+}

package/scaffolds/blank/pages/home/components/hero.tsx

@@ -0,0 +1,34 @@
+const propsSchema = {
+  heading: { type: "string", name: "Heading" },
+  subtitle: { type: "text", name: "Subtitle" },
+} as const;
+
+export const meta = {
+  type: "custom",
+  title: "Hero",
+  order: 0,
+  propsSchema,
+  props: {
+    heading: "",
+    subtitle: "",
+  },
+} as const satisfies FeeefComponentMeta<typeof propsSchema>;
+
+type Props = FeeefLivePropsOf<typeof propsSchema>;
+
+function App() {
+  const p = props as Props;
+  return (
+    <section style={{ padding: "4rem 1.5rem", textAlign: "center" }}>
+      <h1 style={{ fontSize: "2rem", marginBottom: "0.75rem" }}>
+        {p.heading || t("home.heroHeading")}
+      </h1>
+      <p style={{ opacity: 0.8, marginBottom: "1.5rem" }}>
+        {p.subtitle || t("home.heroText")}
+      </p>
+      <a href="/products" style={{ textDecoration: "underline" }}>
+        {t("home.shopNow")}
+      </a>
+    </section>
+  );
+}

package/scaffolds/blank/pages/home/page.json

@@ -0,0 +1,3 @@
+{
+  "props": {}
+}

package/scaffolds/blank/props.json

@@ -0,0 +1,6 @@
+{
+  "theme": {
+    "mode": "system",
+    "rounded": 100
+  }
+}

package/scaffolds/blank/schema.ts

@@ -0,0 +1,49 @@
+/**
+ * Theme schema overlay — merged with Lithium built-ins at `npm run build`.
+ * Published as `StoreTemplate.schema` (via `dist/schema.json`).
+ */
+export const schema = {
+  name: "blank",
+  version: "0.1.0",
+  schema: "1.0",
+  propsSchema: {
+    theme: {
+      name: "Theme",
+      type: "object",
+      propsSchema: {
+        mode: {
+          name: "Color mode",
+          type: "string",
+          tool: {
+            type: "select",
+            options: ["light", "dark", "system"],
+          },
+          default: "system",
+        },
+        rounded: {
+          name: "Corner roundness %",
+          type: "number",
+          tool: { type: "slider", min: 0, max: 500, step: 1 },
+          default: 100,
+        },
+      },
+    },
+  },
+  pages: {
+    home: {
+      name: "Home",
+      path: "/",
+      sections: {
+        main: {},
+      },
+      layout: {
+        sm: [
+          {
+            type: "column",
+            children: ["main"],
+          },
+        ],
+      },
+    },
+  },
+} as const satisfies FeeefThemeSchema;

package/scaffolds/blank/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "checkJs": false,
+    "strict": false,
+    "noImplicitAny": false,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "types": []
+  },
+  "include": ["types", "pages", "shared", "library", "schema.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/scaffolds/blank/types/feeef-live-scope.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Ambient types for Feeef theme component `.tsx` files.
+ *
+ * Custom components run in react-live: these names are injected at runtime
+ * (no imports). This file teaches VS Code / tsserver those globals and
+ * derives props types from `propsSchema`.
+ *
+ * @see docs/03-CUSTOM-COMPONENTS.md
+ * @see docs/04-WORKFLOW.md
+ */
+
+/// <reference types="react" />
+
+// ─── propsSchema → TypeScript ───────────────────────────────────────────────
+
+/** Field definition inside `meta.propsSchema` (Lithium PropDef). */
+type FeeefPropDef = {
+  type:
+    | "string"
+    | "number"
+    | "boolean"
+    | "text"
+    | "array"
+    | "object"
+    | "color"
+    | "image"
+    | (string & {});
+  tool?: unknown;
+  default?: unknown;
+  items?: FeeefPropDef | { type: string; propsSchema?: FeeefPropsSchema };
+  propsSchema?: FeeefPropsSchema;
+  name?: string;
+  [key: string]: unknown;
+};
+
+type FeeefPropsSchema = Record<string, FeeefPropDef>;
+
+/** Map a single PropDef to a TS value type. */
+type FeeefPropValue<D> = D extends { type: "number" }
+  ? number
+  : D extends { type: "boolean" }
+    ? boolean
+    : D extends { type: "array"; items: infer I }
+      ? FeeefPropValue<I>[]
+      : D extends { type: "object"; propsSchema: infer PS extends FeeefPropsSchema }
+        ? FeeefPropsFromSchema<PS>
+        : D extends { type: "string" | "text" | "color" | "image" }
+          ? string
+          : D extends { type: string }
+            ? unknown
+            : unknown;
+
+/** Props object inferred from a `propsSchema` const. */
+type FeeefPropsFromSchema<S> = {
+  [K in keyof S]: S[K] extends FeeefPropDef ? FeeefPropValue<S[K]> : unknown;
+};
+
+/**
+ * Live `props` shape for a schema: schema fields + slots chrome.
+ *
+ * @example
+ * ```ts
+ * const propsSchema = { heading: { type: "string" } } as const;
+ * type Props = FeeefLivePropsOf<typeof propsSchema>;
+ * function App() {
+ *   const p = props as Props;
+ *   return <h1>{p.heading}</h1>;
+ * }
+ * ```
+ */
+type FeeefLivePropsOf<S> = FeeefPropsFromSchema<S> & {
+  slots?: Record<string, React.ReactNode | React.ReactNode[] | undefined>;
+  slotsLayout?: unknown;
+};
+
+/**
+ * Use with `satisfies` so `meta.props` must match `meta.propsSchema`.
+ *
+ * @example
+ * ```ts
+ * export const meta = { …, propsSchema, props } as const satisfies FeeefComponentMeta<typeof propsSchema>;
+ * ```
+ */
+type FeeefComponentMeta<
+  S extends FeeefPropsSchema = FeeefPropsSchema,
+> = {
+  type?: string;
+  instanceId?: string;
+  title?: string;
+  order?: number;
+  propsSchema?: S;
+  props?: FeeefPropsFromSchema<S>;
+  slotsSchema?: Record<string, { name?: string | null; maxChildren?: number | null }>;
+  slotsLayout?: unknown;
+  slots?: Record<string, unknown> | null;
+  children?: unknown[] | null;
+  refId?: string;
+  refVersion?: number;
+  [key: string]: unknown;
+};
+
+/** Untyped fallback (marketplace / legacy). Prefer `FeeefLivePropsOf<typeof propsSchema>`. */
+interface FeeefLiveProps {
+  [key: string]: any;
+  slots?: Record<string, any>;
+  slotsLayout?: any;
+}
+
+declare const React: typeof import("react");
+
+/** Template props for this component (react-live scope). Cast with `FeeefLivePropsOf<…>`. */
+declare const props: FeeefLiveProps;
+
+declare const useState: typeof import("react").useState;
+declare const useEffect: typeof import("react").useEffect;
+declare const useLayoutEffect: typeof import("react").useLayoutEffect;
+declare const useRef: typeof import("react").useRef;
+declare const useMemo: typeof import("react").useMemo;
+declare const useCallback: typeof import("react").useCallback;
+
+declare function useStore(): any;
+declare function useFeeef(): any;
+declare function useFeeefCart(): any;
+declare function useCurrentProduct(): any;
+declare function useTemplate(): any;
+declare function useTheme(): any;
+
+declare function t(key: string, params?: any): string;
+declare function useFeeefT(): typeof t;
+declare function useFeeefLocale(): string;
+declare function getFeeefLocale(): string;
+declare function getFeeefDir(): "rtl" | "ltr";
+
+declare function useRouter(): any;
+declare function usePathname(): string;
+declare function useSearchParams(): any;
+
+declare const Link: React.ComponentType<any>;
+
+/** Nav helper — object API and/or JSX depending on theme code. */
+declare const RouterNav: React.ComponentType<any> & {
+  push: (href: string) => void;
+  replace: (href: string) => void;
+  [key: string]: any;
+};
+
+declare const SlotsLayout: React.ComponentType<any>;
+declare const SlotContextBridge: React.ComponentType<any>;
+declare function useSlotContext(key: string): any;
+
+declare function dartColorToCssColor(dartColor: any): string | null;
+declare function convertDartColorToCssNumber(dartColor: any): number | null;
+declare function cssColorToHslString(color: any): string | null;
+
+interface Window {
+  fbq?: (...args: any[]) => void;
+  [key: string]: any;
+}
+
+interface CSSProperties {
+  [key: `--${string}`]: string | number | undefined;
+}

package/scaffolds/blank/types/feeef-template-schema.d.ts

@@ -0,0 +1,84 @@
+/**
+ * TypeScript types for theme-owned `schema.ts` overlays.
+ *
+ * Author with:
+ * ```ts
+ * export const schema = { … } as const satisfies FeeefThemeSchema;
+ * ```
+ *
+ * Build merges this with Lithium built-ins → `dist/schema.json`.
+ */
+
+/** Field definition (same shape as component propsSchema / Lithium PropDef). */
+type FeeefSchemaPropDef = {
+  type:
+    | "string"
+    | "number"
+    | "boolean"
+    | "text"
+    | "array"
+    | "object"
+    | "color"
+    | "image"
+    | (string & {});
+  name?: string;
+  description?: string;
+  default?: unknown;
+  tool?: unknown;
+  items?: FeeefSchemaPropDef | { type: string; propsSchema?: FeeefSchemaPropsMap };
+  propsSchema?: FeeefSchemaPropsMap;
+  [key: string]: unknown;
+};
+
+type FeeefSchemaPropsMap = Record<string, FeeefSchemaPropDef>;
+
+/** Built-in / catalog component entry in schema.components. */
+type FeeefSchemaComponentDef = {
+  name?: string;
+  category?: string;
+  description?: string;
+  acceptsChildren?: boolean;
+  propsSchema?: FeeefSchemaPropsMap;
+  [key: string]: unknown;
+};
+
+/** One section key under a page (e.g. main). */
+type FeeefSchemaSectionDef = {
+  propsSchema?: FeeefSchemaPropsMap;
+  [key: string]: unknown;
+};
+
+/** Responsive layout node used by the merchant editor. */
+type FeeefSchemaLayoutNode = {
+  type: string;
+  children?: Array<string | FeeefSchemaLayoutNode>;
+  [key: string]: unknown;
+};
+
+type FeeefSchemaPageDef = {
+  name?: string;
+  path?: string;
+  description?: string;
+  propsSchema?: FeeefSchemaPropsMap;
+  sections: Record<string, FeeefSchemaSectionDef>;
+  layout?: Record<string, FeeefSchemaLayoutNode[]>;
+  [key: string]: unknown;
+};
+
+/**
+ * Theme schema overlay (and full packaged schema shape).
+ *
+ * - `pages` + `propsSchema` are theme-controlled.
+ * - `components` is optional; merged onto Lithium built-ins at build.
+ */
+type FeeefThemeSchema = {
+  name: string;
+  version: string;
+  /** Schema format version (Lithium uses `"1.0"`). */
+  schema?: string;
+  propsSchema?: FeeefSchemaPropsMap;
+  pages: Record<string, FeeefSchemaPageDef>;
+  components?: Record<string, FeeefSchemaComponentDef>;
+  library?: unknown[];
+  [key: string]: unknown;
+};

package/vendor/template-kit/README.md

@@ -0,0 +1,64 @@
+# Feeef Template Kit
+
+Author Lithium templates as a **folder tree** (real `.jsx` files + JSON schemas), then compile to the `data.json` blob Feeef already understands.
+
+**AI / engineer docs (start here):** [`../templates/AGENTS.md`](../templates/AGENTS.md) · [`../templates/docs/`](../templates/docs/)
+
+
+```
+pages/home/sections/header/components/dawn-shell/
+  component.json    # type, props, propsSchema, slotsSchema, …
+  component.jsx     # function App() { … }  → becomes "code"
+  slots/sections/…  # nested components
+```
+
+## Quick demo (from `storefront/`)
+
+```bash
+# 1) Split the Dawn theme into a source tree
+npm run template:unpack
+
+# 2) Compile back to dist/data.json
+npm run template:build
+
+# 3) Run Lithium with the local override (dev only)
+npm run template:dev
+```
+
+Open the storefront, edit any `component.jsx`, save — with `template:watch` (or `template:dev`) the dist file rebuilds; refresh the page to see it.
+
+## Commands
+
+| Script | What it does |
+|---|---|
+| `npm run template:unpack` | `templates/down/data.json` → `templates/dawn-src/` |
+| `npm run template:build` | `dawn-src/` → `dawn-src/dist/data.json` |
+| `npm run template:check` | Validate without writing |
+| `npm run template:watch` | Rebuild on file change |
+| `npm run template:dev` | Watch + `next dev` with `FEEEF_TEMPLATE_DATA_PATH` set |
+
+CLI entry: `node template-kit/bin/feeef-template.mjs <cmd>`.
+
+## Dev override
+
+When `NODE_ENV=development` and `FEEEF_TEMPLATE_DATA_PATH` points at a `data.json` file, Lithium's server-only `getTemplate()` (`utils/get-template.ts`) loads that file on every request (no cache) instead of `store.metadata.templateData`. Production ignores the env var. The loader is intentionally separate from `@/utils/template` so `node:fs` never enters the client bundle.
+
+## Conventions
+
+| Disk | Maps to |
+|---|---|
+| `feeef.template.json` | Manifest (name, page order) |
+| `props.json` | Root `props` (theme, …) |
+| `pages/<id>/page.json` | Page `props` |
+| `…/components/<name>/component.json` | Component meta (+ `order`) |
+| `component.jsx` | `code` (custom components) |
+| `slots/<slotId>/<child>/` | `slots[slotId][]` |
+| `children/<child>/` | `children[]` (grid/flex/container) |
+| `shared/components/<id>/` | Theme library — placements use `$ref: "shared.<id>"` |
+| `$ref` / `shared` in placement json | Expanded at build (not left in dist) |
+
+Add `"$schema": "../../template-kit/schemas/component.schema.json"` in `component.json` for IDE autocomplete.
+
+## Shared components
+
+See [`../templates/docs/07-SHARED-COMPONENTS.md`](../templates/docs/07-SHARED-COMPONENTS.md). UI reused across pages **must** live under `shared/components/`.

package/vendor/template-kit/bin/dev.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Build once, then run template:watch + next dev with FEEEF_TEMPLATE_DATA_PATH.
+ * Usage (from storefront/): node template-kit/bin/dev.mjs
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildTemplate } from "../lib/build.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const storefrontRoot = path.resolve(__dirname, "../..");
+const srcDir = path.join(storefrontRoot, "templates/dawn-src");
+const dataPath = path.join(srcDir, "dist/data.json");
+const libraryPath = path.join(srcDir, "dist/schema.library.json");
+const cli = path.join(__dirname, "feeef-template.mjs");
+
+function run() {
+  try {
+    buildTemplate({ srcDir, outPath: dataPath, write: true });
+    console.log(`[template-kit] dist ready → ${path.relative(storefrontRoot, dataPath)}`);
+  } catch (e) {
+    console.error(`[template-kit] initial build failed: ${e.message || e}`);
+    process.exit(1);
+  }
+
+  const env = {
+    ...process.env,
+    FEEEF_TEMPLATE_DATA_PATH: dataPath,
+    FEEEF_TEMPLATE_LIBRARY_PATH: libraryPath,
+  };
+
+  const watch = spawn(
+    process.execPath,
+    [cli, "watch", srcDir, "-o", dataPath],
+    { cwd: storefrontRoot, env, stdio: "inherit" },
+  );
+
+  const next = spawn(
+    "npx",
+    ["next", "dev", "--turbopack"],
+    { cwd: storefrontRoot, env, stdio: "inherit", shell: true },
+  );
+
+  const shutdown = (code) => {
+    watch.kill("SIGTERM");
+    next.kill("SIGTERM");
+    process.exit(code ?? 0);
+  };
+
+  watch.on("exit", (code) => {
+    if (code && code !== 0) shutdown(code);
+  });
+  next.on("exit", (code) => shutdown(code ?? 0));
+
+  process.on("SIGINT", () => shutdown(0));
+  process.on("SIGTERM", () => shutdown(0));
+}
+
+run();