@synap-core/workspace-templates 0.11.0 → 0.23.0

package/src/social.yaml

@@ -13,6 +13,11 @@ meta:
   color: "#1D9BF0"
   tags: [social, distribution, publishing, channels]
   isPublic: true
+  # What this space PRODUCES (homes): the purpose word, then its kinds/roles.
+  intent:
+    label: Distribution
+    produces:
+      - profile: post
 
 # Social REUSES Content OS's pod-wide `platform` (publishing-account) vocabulary
 # instead of forking its own `channel` kind. `platform` is `scope: shared` in
@@ -23,7 +28,7 @@ dependencies:
   - slug: content-os
     kind: workspace
     relation: require
-    reason: "Reuses Content OS's shared platform (publishing-account) vocabulary."
+    reason: "Reuses Content OS's shared platform (publishing-account) and post vocabulary."
 
 workspace:
   name: Social
@@ -125,44 +130,97 @@ profiles:
       - slug: platform-tags
         label: Tags
         valueType: array
+      # ── Postiz channel (the `postiz` capability) ─────────────────────────
+      # Which Postiz channel this account is, both read from
+      # postiz_list_integrations: its id, and its provider (the `identifier`
+      # a post's `settings.__type` names: x, linkedin, instagram…). A post
+      # queued on this account passes both to postiz_schedule_post.
+      - slug: postiz-integration-id
+        label: Postiz channel ID
+        valueType: string
+        inputType: text
+      - slug: postiz-provider
+        label: Postiz provider
+        valueType: string
+        inputType: text
 
-  - slug: social-post
+  # ── Post (shared post kind — SSOT is content-os.yaml) ──────────────────────
+  # RE-DECLARED, like `platform` above: this declaration writes the grant that
+  # puts the ONE pod-wide `post` kind in this workspace. The old `social-post`
+  # twin is folded into it by the w11.post.* manifest ops (plan D2); its
+  # `failed` status became `publish-outcome` (plan D12). Only the properties
+  # Social uses are re-declared, each byte-identical to content-os's.
+  - slug: post
     displayName: Post
-    icon: send
-    color: "#0EA5E9"
-    description: "A single piece going out on a channel — its content, its schedule, and where it landed."
+    icon: file-edit
+    color: "#6366F1"
+    description: "Your atomic content unit. One idea, multiple platform formats — tracked from spark to publication."
+    scope: shared
+    # The ONE lifecycle (work model L1): every option's category.
+    lifecycle:
+      property: post-status
+      options:
+        - { key: Idea, category: open }
+        - { key: Briefed, category: active }
+        - { key: Scripted, category: active }
+        - { key: "In Draft", category: active }
+        - { key: Review, category: active }
+        - { key: Scheduled, category: active }
+        - { key: Published, category: done }
+        - { key: Archived, category: lost, humanOnly: true }
+    # How it renders (entity rendering, decision 8): @synap-core/types/presentation.
+    presentation:
+      family: work
     properties:
       - slug: post-status
         label: Status
         valueType: string
         inputType: select
-        enumValues: [draft, scheduled, published, failed]
-        constraints: { defaultValue: draft }
-      - slug: post-platform
-        label: Platform
+        enumValues:
+          [
+            "Idea",
+            "Briefed",
+            "Scripted",
+            "In Draft",
+            "Review",
+            "Scheduled",
+            "Published",
+            "Archived",
+          ]
+      - slug: post-account
+        label: Account
         valueType: entity_id
         targetProfileSlug: platform
         inputType: entity_select
-      - slug: post-content
-        label: Content
+      - slug: publish-date
+        label: Publish Date
+        valueType: date
+      - slug: post-url
+        label: Published URL
+        valueType: string
+        inputType: text
+        placeholder: "https://..."
+        constraints: { format: url }
+      - slug: publish-outcome
+        label: Publish outcome
+        valueType: string
+        inputType: select
+        enumValues: [succeeded, failed, queued, sending, waiting]
+      - slug: publish-error
+        label: Publish error
         valueType: string
         inputType: textarea
-      - slug: scheduled-at
-        label: Scheduled For
-        valueType: date
-        inputType: date
       - slug: published-at
         label: Published At
         valueType: date
         inputType: date
-      - slug: post-url
-        label: Post URL
-        valueType: string
-        inputType: url
-      - slug: post-notes
-        label: Notes
+      # ── Postiz (the `postiz` capability) ─────────────────────────────────
+      # The post's id in the person's Postiz, recorded when it is queued there
+      # (postiz_schedule_post returns it). Postiz's webhook finds the post by it.
+      - slug: postiz-post-id
+        label: Postiz post ID
         valueType: string
-        inputType: textarea
+        inputType: text
 
   - slug: post-schedule
     displayName: Schedule
@@ -238,9 +296,9 @@ views:
   - name: Content Calendar
     slug: content-calendar
     type: kanban
-    scopeProfileSlug: social-post
+    scopeProfileSlug: post
     groupBy: post-status
-    description: "Posts on a board by status — draft to published."
+    description: "Posts on a board by status — idea to published."
   - name: Platforms
     slug: platforms
     type: table
@@ -268,10 +326,10 @@ onboarding:
       what: The platforms you actually publish on — one per real account, with its type and handle.
       cardinality: few
       keyFields: [platform-type, handle]
-    - profileSlug: social-post
-      what: The posts in motion — drafts, scheduled, and recently published — each tied to its platform.
+    - profileSlug: post
+      what: The posts in motion — drafts, scheduled, and recently published — each tied to its account.
       cardinality: several
-      keyFields: [post-status, post-platform]
+      keyFields: [post-status, post-account]
   openingQuestions:
     - "Which channels are you actually active on right now, and which one earns the most attention?"
     - "What's your posting cadence per channel — daily, weekly, ad-hoc?"

package/src/space-packages.freshness.test.ts

@@ -0,0 +1,97 @@
+/**
+ * FRESHNESS GATE for the generated-and-committed `src/space-packages.generated.ts`.
+ *
+ * A space package bundles ONLY its own modules
+ * (`packages/web/src/space-packages/`). The shared components come from the
+ * host's `@synap/kit` frame module (`packages/web/src/space-packages/kit.ts`,
+ * built into `packages/web/src/cell-runtime/frame-host-modules.generated.ts`,
+ * whose own freshness test sits beside it), React from the host's React
+ * modules. The build is committed, so it can go stale: a package source
+ * changes, nobody rebuilds, and the space keeps shipping the old code. This
+ * test re-reads what the build recorded: every repo file the bundle read must
+ * still hash the same.
+ *
+ * It also pins the KIT CONTRACT: every name a package imports from
+ * `@synap/kit` is one the host's kit exports, so a kit change that drops a
+ * name fails here, not as a frame that cannot link.
+ *
+ * And it pins the declaration to the build: every template's
+ * `spacePackage.cells[]` is built (same key, same source), and nothing is
+ * built for a cell no template declares.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { readYamlTemplates } from './generate.mjs';
+import { BUILT_SPACE_PACKAGES } from './space-packages.generated';
+import { hostRequiresIn, kitImportsIn } from './frame-host-modules.mjs';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+const REBUILD = 'pnpm --filter @synap-core/workspace-templates build:space-packages';
+const SPACE_PACKAGES_DIR = 'packages/web/src/space-packages/';
+const HOST_MODULES_FILE = join(REPO_ROOT, 'packages/web/src/cell-runtime/frame-host-modules.generated.ts');
+
+function sha256(path: string): string {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+/** The names the host's kit exports, read from the host's generated file (no cross-package import). */
+function hostKitExports(): string[] {
+  const m = /export const FRAME_KIT_EXPORTS: readonly string\[\] = (\[[^\]]*\]);/.exec(readFileSync(HOST_MODULES_FILE, 'utf8'));
+  if (!m) throw new Error(`no FRAME_KIT_EXPORTS in ${HOST_MODULES_FILE}`);
+  return JSON.parse(m[1]!) as string[];
+}
+
+const declared = readYamlTemplates().flatMap(({ slug, data }) =>
+  ((data?.spacePackage?.cells ?? []) as Array<{ key: string; source: string }>).map((c) => ({ slug, ...c }))
+);
+
+describe('space-packages.generated.ts freshness', () => {
+  it('builds exactly the cells the templates declare', () => {
+    const built = Object.entries(BUILT_SPACE_PACKAGES).flatMap(([slug, pkg]) =>
+      pkg.cells.map((c) => ({ slug, key: c.key, source: c.source }))
+    );
+    const id = (c: { slug: string; key: string; source: string }) => `${c.slug}:${c.key} ← ${c.source}`;
+    expect(built.map(id).sort(), `stale space packages — run: ${REBUILD}`).toEqual(declared.map(id).sort());
+  });
+
+  for (const [slug, pkg] of Object.entries(BUILT_SPACE_PACKAGES)) {
+    it(`${slug}: every repo file the bundle read is unchanged`, () => {
+      const changed = Object.entries(pkg.inputs)
+        .filter(([path, hash]) => !existsSync(join(REPO_ROOT, path)) || sha256(join(REPO_ROOT, path)) !== hash)
+        .map(([path]) => path);
+      expect(changed, `space package "${slug}" was built from an older source — run: ${REBUILD}`).toEqual([]);
+    });
+
+    it(`${slug}: it bundles only its own modules; the shared layers come from the host's kit`, () => {
+      const inputs = Object.keys(pkg.inputs);
+      expect(inputs.length).toBeGreaterThan(0);
+      expect(inputs.filter((p) => !p.startsWith(SPACE_PACKAGES_DIR))).toEqual([]);
+      expect(inputs).not.toContain(`${SPACE_PACKAGES_DIR}kit.ts`);
+    });
+
+    it(`${slug}: every name it imports from @synap/kit is one the host's kit exports`, () => {
+      const exported = hostKitExports();
+      for (const cell of pkg.cells) {
+        // The record is the code's own imports, not a hand-kept list.
+        expect(cell.kitImports, cell.key).toEqual(kitImportsIn(cell.code));
+        expect(cell.kitImports.length, cell.key).toBeGreaterThan(0);
+        const missing = cell.kitImports.filter((n) => !exported.includes(n));
+        expect(missing, `${slug}:${cell.key} imports names the host's kit no longer exports — run: ${REBUILD}`).toEqual([]);
+      }
+    });
+
+    it(`${slug}: the bundle runs as a network-contained frame module`, () => {
+      for (const cell of pkg.cells) {
+        // A frame has no network origin for code: esm.sh is in no frame's CSP.
+        expect(cell.code.includes('esm.sh'), cell.key).toBe(false);
+        expect(cell.code.length, cell.key).toBeGreaterThan(0);
+        // A CJS `require()` of a host module throws in the frame (esbuild's
+        // `__require` shim): the module would never link.
+        expect(hostRequiresIn(cell.code), cell.key).toEqual([]);
+      }
+    });
+  }
+});

package/src/space-packages.generated.ts

@@ -0,0 +1,40 @@
+// GENERATED by scripts/build-space-packages.mjs from each template's
+// `spacePackage` — do not edit. Rebuild:
+//   pnpm --filter @synap-core/workspace-templates build:space-packages
+// `space-packages.freshness.test.ts` fails when this file no longer matches its sources.
+import type { BuiltSpacePackage } from './space-packages';
+
+export const BUILT_SPACE_PACKAGES: Record<string, BuiltSpacePackage> = {
+  "builder-workspace": {
+    "cells": [
+      {
+        "key": "home",
+        "name": "Work",
+        "source": "packages/web/src/space-packages/builder/home.tsx",
+        "code": "import{useMemo as $}from\"react\";import{installFrameBridge as q}from\"@synap/kit\";import{useCallback as D,useEffect as O,useMemo as T,useState as _}from\"react\";import{LensPageView as x,SpatialAppHeader as M,SpatialButton as W,SpatialPageFrame as j,resolveActionLabel as V,resolveDestinationLabel as Y,resolveObjectNoun as z}from\"@synap/kit\";import{useCallback as E,useEffect as f,useState as g}from\"react\";import{SYNAP_CHANGED_EVENT as b,useLensPageClock as R,useLensPageModelOf as B}from\"@synap/kit\";var C=\"lens.page\",F=750;function H(e){if(!e||typeof e!=\"object\")return new Error(\"The lens page read returned nothing\");let t=e;return typeof t.error==\"string\"?new Error(t.error):!t.page||typeof t.page!=\"object\"?new Error(\"The lens page read returned no page\"):t.page}function S(e,t){let n=R(t),{since:o}=n,[i,c]=g({status:\"loading\",page:null,error:null}),[m,u]=g(0);f(()=>{if(!t)return;let s=!0;return c(r=>({...r,status:r.page?r.status:\"loading\"})),e.query(C,o?{since:o}:{}).then(r=>{if(!s)return;let p=H(r);c(p instanceof Error?{status:\"failed\",page:null,error:p.message}:{status:\"ready\",page:p,error:null})}).catch(r=>{s&&c({status:\"failed\",page:null,error:String(r)})}),()=>{s=!1}},[e,t,o,m]),f(()=>{if(!t)return;let s,r=()=>{s===void 0&&(s=setTimeout(()=>{s=void 0,u(v=>v+1)},F))},p=()=>{document.visibilityState===\"visible\"&&r()};document.addEventListener(\"visibilitychange\",p),window.addEventListener(\"focus\",r);let h=e.subscribe(\"entity:changed\",r),P=e.subscribe(b,r);return()=>{clearTimeout(s),document.removeEventListener(\"visibilitychange\",p),window.removeEventListener(\"focus\",r),h(),P()}},[e,t]);let a=B(i.page,n),l=E(()=>u(s=>s+1),[]);return{model:a,status:a?i.status:i.status===\"failed\"?\"failed\":\"loading\",error:i.error,refetch:l,today:n.today}}import{encodeActivityScope as I,encodeLensScope as y,lensActivityScope as A}from\"@synap/kit\";function N(e,t){let n=y(e);return{blocking:{kind:\"app\",appId:\"inbox\",props:{scope:n}},happening:{kind:\"app\",appId:\"sessions\",props:{view:\"sessions\",scope:n,narrow:\"running\"}},produced:{kind:\"app\",appId:\"data\",props:{view:\"landed\",scope:I(A(e))}},happened:{kind:\"app\",appId:\"sessions\",props:{view:\"activity\",day:t,scope:n}}}}function L(e){return{kind:\"app\",appId:\"sessions\",props:{view:\"plan\",scope:y(e)}}}function k(e,t,n){let o=N(t,n);return{blocking:()=>e(o.blocking),happening:()=>e(o.happening),produced:()=>e(o.produced),happened:()=>e(o.happened)}}import{jsx as d}from\"react/jsx-runtime\";var G=\"Open a decision to answer it on its own page.\";function U(e){let[t,n]=_(null);return O(()=>{e.onInit(o=>n({scope:o.workspaceId?{kind:\"workspace\",workspaceId:o.workspaceId}:{kind:\"pod\"},name:o.workspaceName?.trim()||null}))},[e]),t}function w({bridge:e}){let t=U(e),n=t?.scope??null,o=S(e,n),i=D((a,l)=>e.openSurface({kind:\"object\",objectKind:a.kind,objectId:a.id,...a.view?{view:a.view}:{},...l?{title:l}:{}}),[e]),c=T(()=>n?k(a=>e.openSurface(a),n,o.today):{},[e,n,o.today]),m=Y(\"work\"),u=o.status===\"ready\"&&(o.model?.blocking.items.length??0)>0;return d(j,{className:\"space-work-home\",template:\"hub\",layout:\"column\",width:\"list\",header:d(M,{size:\"lg\",title:t?.name??z(\"workspace\"),...u?{subtitle:G}:{},...n?{actions:d(W,{size:\"sm\",variant:\"secondary\",onClick:()=>e.openSurface(L(n)),children:`${V(\"open\")} in ${m}`})}:{}}),children:d(x,{scope:n??{kind:\"pod\"},model:n?o.model:null,status:n?o.status:\"loading\",onRetry:o.refetch,today:o.today,doors:c,onOpen:i,columns:!0})})}import{jsx as Q}from\"react/jsx-runtime\";function K(){let e=$(()=>q(),[]);return Q(w,{bridge:e})}export{K as default};\n",
+        "kitImports": [
+          "LensPageView",
+          "SYNAP_CHANGED_EVENT",
+          "SpatialAppHeader",
+          "SpatialButton",
+          "SpatialPageFrame",
+          "encodeActivityScope",
+          "encodeLensScope",
+          "installFrameBridge",
+          "lensActivityScope",
+          "resolveActionLabel",
+          "resolveDestinationLabel",
+          "resolveObjectNoun",
+          "useLensPageClock",
+          "useLensPageModelOf"
+        ]
+      }
+    ],
+    "inputs": {
+      "packages/web/src/space-packages/builder/home.tsx": "7afed696a23b1a474eace193d85688233e2f652e5e4ca56926edc8e1a16e62ef",
+      "packages/web/src/space-packages/frame-doors.ts": "662fbd70165f21a758b8677ac7a1169030f76996921e322159ccd67e19ee7520",
+      "packages/web/src/space-packages/frame-lens.ts": "627d26ad593a327f4d3cb50ceb3f04529200f99bb97719d02edc346ff60c2073",
+      "packages/web/src/space-packages/SpaceWorkHome.tsx": "e44497878da09b9ac0e9356440196e5973329a5ddef462991d9deb7087444718"
+    }
+  }
+};

package/src/space-packages.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { toPackageDefinition, toWorkspaceDefinition } from './define.js';
+import { spacePackageCells, type BuiltSpacePackage } from './space-packages.js';
+import type { WorkspaceYaml } from './types.js';
+import { validateTemplate } from './validate.js';
+
+const SOURCE = 'packages/web/src/space-packages/fixture/home.tsx';
+
+function template(overrides: Partial<Pick<WorkspaceYaml, 'app' | 'layout' | 'spacePackage'>>): WorkspaceYaml {
+  return {
+    meta: {
+      slug: 'space-package-test',
+      name: 'Space package test',
+      description: 'Space package fixture',
+      icon: 'panels-top-left',
+      color: 'blue',
+    },
+    workspace: { name: 'Space package test', description: 'Space package fixture' },
+    profiles: [{ slug: 'thing', displayName: 'Thing', properties: [] }],
+    ...overrides,
+  };
+}
+
+const withPackage = (app?: WorkspaceYaml['app']) =>
+  template({
+    ...(app ? { app } : {}),
+    spacePackage: { cells: [{ key: 'home', name: 'Home', source: SOURCE }] },
+  });
+
+const built: Record<string, BuiltSpacePackage> = {
+  'space-package-test': {
+    cells: [{ key: 'home', name: 'Home', source: SOURCE, code: 'export default function Home() { return null; }', kitImports: [] }],
+    inputs: {},
+  },
+};
+
+const rules = (tpl: WorkspaceYaml) => validateTemplate(tpl).errors.map((e) => e.rule);
+
+describe('space package cells', () => {
+  it('carries each built module as a network-contained frame cell', () => {
+    expect(spacePackageCells(withPackage(), built)).toEqual([
+      { key: 'home', name: 'Home', code: built['space-package-test'].cells[0].code, rendererType: 'frame' },
+    ]);
+  });
+
+  it('has no cells for a template without a space package', () => {
+    expect(spacePackageCells(template({}), built)).toBeUndefined();
+  });
+
+  it('refuses a declared cell that was never built: no space opens "Unknown cell"', () => {
+    expect(() => spacePackageCells(withPackage(), {})).toThrow(/not built/);
+    const otherSource = { 'space-package-test': { ...built['space-package-test'], cells: [{ ...built['space-package-test'].cells[0], source: 'packages/web/src/space-packages/fixture/old.tsx' }] } };
+    expect(() => spacePackageCells(withPackage(), otherSource)).toThrow(/not built/);
+  });
+
+  it('travels on the package definition only: the workspace door has no cells', () => {
+    expect('cells' in toWorkspaceDefinition(withPackage())).toBe(false);
+    expect('cells' in toPackageDefinition(template({}))).toBe(false);
+  });
+});
+
+describe('space package validation', () => {
+  it('accepts an entry that opens a cell the template installs', () => {
+    expect(rules(withPackage({ kind: 'stored', cellKey: 'cell:space-package-test:home' }))).not.toContain(
+      'space-package-entry-unknown'
+    );
+  });
+
+  it('refuses an entry naming a package cell the template does not build', () => {
+    expect(rules(withPackage({ kind: 'stored', cellKey: 'cell:space-package-test:other' }))).toContain(
+      'space-package-entry-unknown'
+    );
+    expect(rules(template({ app: { kind: 'stored', cellKey: 'cell:space-package-test:home' } }))).toContain(
+      'space-package-entry-unknown'
+    );
+    // Another package's namespace is never this template's to open.
+    expect(rules(withPackage({ kind: 'stored', cellKey: 'cell:crm:home' }))).toContain('space-package-entry-unknown');
+  });
+
+  it('checks the authored layout.primarySurface the same way', () => {
+    const tpl = template({
+      layout: { primarySurface: { kind: 'cell', cellKey: 'cell:space-package-test:home' } },
+    });
+    expect(rules(tpl)).toContain('space-package-entry-unknown');
+  });
+
+  it('leaves built-in cell keys alone', () => {
+    expect(rules(template({ app: { kind: 'stored', cellKey: 'content-home' } }))).not.toContain(
+      'space-package-entry-unknown'
+    );
+  });
+
+  it('builds only from the shared components under packages/web/src/space-packages/', () => {
+    const bad = (source: string) =>
+      rules(template({ spacePackage: { cells: [{ key: 'home', name: 'Home', source }] } }));
+    expect(bad('apps/devplane/page.tsx')).toContain('space-package-cell-source');
+    expect(bad('packages/web/src/space-packages/../../../../etc/x.ts')).toContain('space-package-cell-source');
+    expect(bad('packages/web/src/space-packages/x/home.css')).toContain('space-package-cell-source');
+    expect(bad(SOURCE)).not.toContain('space-package-cell-source');
+  });
+
+  it('needs unique kebab-case keys', () => {
+    const tpl = template({
+      spacePackage: {
+        cells: [
+          { key: 'home', name: 'Home', source: SOURCE },
+          { key: 'home', name: 'Home again', source: SOURCE },
+          { key: 'Home Page', name: 'Bad', source: SOURCE },
+        ],
+      },
+    });
+    expect(rules(tpl)).toEqual(expect.arrayContaining(['space-package-cell-key-duplicate', 'space-package-cell-key']));
+  });
+});
+
+describe('the Builder space opens its own built code', () => {
+  it('installs the cell its app opens', () => {
+    const def = toPackageDefinition('builder-workspace');
+    const surface = def.layoutConfig?.primarySurface;
+    expect(surface).toMatchObject({ kind: 'cell', cellKey: 'cell:builder-workspace:home' });
+    expect(def.cells?.map((c) => c.key)).toEqual(['home']);
+    expect(def.cells?.[0]).toMatchObject({ rendererType: 'frame' });
+    expect(def.cells?.[0].code.length).toBeGreaterThan(0);
+  });
+});

package/src/space-packages.ts

@@ -0,0 +1,73 @@
+/**
+ * Space packages: the built code a template installs in its space.
+ *
+ * `scripts/build-space-packages.mjs` bundles each template's
+ * `spacePackage.cells[]` into `space-packages.generated.ts` (committed, like
+ * `templates.ts`, so every consumer of `toPackageDefinition` gets the same
+ * cells without a bundler). This module reads that output for the converter.
+ */
+import type { WorkspaceYaml } from './types';
+import { BUILT_SPACE_PACKAGES } from './space-packages.generated.js';
+
+/** One built module: the declared cell plus its bundled ES module source. */
+export interface BuiltSpacePackageCell {
+  key: string;
+  name: string;
+  source: string;
+  /** The ES module the frame runs (default export = a React component). */
+  code: string;
+  /**
+   * Every name the module imports from the host's `@synap/kit` frame module:
+   * the kit contract it was built against (the build refused any name the kit
+   * did not export).
+   */
+  kitImports: string[];
+}
+
+/**
+ * A template's built space package. It bundles only its own modules
+ * (`packages/web/src/space-packages/`): the shared layers come from the host's
+ * kit, whose own build record is `FRAME_HOST_MODULES_BUILD`
+ * (`@synap-core/web` cell-runtime).
+ */
+export interface BuiltSpacePackage {
+  cells: BuiltSpacePackageCell[];
+  /** sha256 of every synap-app file the bundles read (repo-relative path → hex). */
+  inputs: Record<string, string>;
+}
+
+/**
+ * A space package cell on the package wire (`PackageDefinition.cells[]`, the
+ * pod's `PackageCellDef`): a sandboxed `frame` cell. No `externalHosts`: a
+ * space package is network-contained; its only data path is the host bridge.
+ */
+export interface SpacePackageCellWire {
+  key: string;
+  name: string;
+  code: string;
+  rendererType: 'frame';
+}
+
+/**
+ * The cells a template's space package installs, or `undefined` when it has
+ * none. Throws when a declared cell was never built (or was built from another
+ * source): a template must never ship an entry that opens "Unknown cell".
+ */
+export function spacePackageCells(
+  tpl: WorkspaceYaml,
+  built: Record<string, BuiltSpacePackage> = BUILT_SPACE_PACKAGES
+): SpacePackageCellWire[] | undefined {
+  const declared = tpl.spacePackage?.cells;
+  if (!declared?.length) return undefined;
+  const pkg = built[tpl.meta.slug];
+  return declared.map((cell) => {
+    const b = pkg?.cells.find((c) => c.key === cell.key && c.source === cell.source);
+    if (!b) {
+      throw new Error(
+        `Space package cell "${cell.key}" of template "${tpl.meta.slug}" is not built from ${cell.source}: ` +
+          'run pnpm --filter @synap-core/workspace-templates build:space-packages'
+      );
+    }
+    return { key: cell.key, name: cell.name, code: b.code, rendererType: 'frame' };
+  });
+}