@assembly-js/app-foundation 0.0.8-rc.0 → 0.0.9

package/CLAUDE.md

@@ -10,6 +10,10 @@ In user-facing chat, never mention ASSEMBLY_ENV, COPILOT_ENV, or any other inter
 
 **If an SDK auth warning appears mid-build** — for example, a "You must set ASSEMBLY_ENV=local" message from the SDK initializer — treat it as expected transient state. The sandbox resolves it automatically as the build progresses. Do not surface this message in chat and do not ask the user to set any environment variables.
 
+When you describe a feature or a change, describe what the user and their clients will **experience** — who can open the app, what each audience sees or can do. The mechanics that produce it are plumbing too: keep manifest keys (`surfaces`, `app.json`), file names, SDK method names, and identity fields like `clientId`/`internalUserId` out of chat unless the user asks how it works. "Clients will see only their own record" is something they can act on; "add a client surface to the manifest and branch on `identity.clientId`" is not.
+
+When a request implies a scope or permission change, apply it and report the product effect — don't stop to ask the user to approve the mechanics. "When a client views this, show them their own info" already means "make this client-facing," so make the change and say what happened ("clients now see just their own record; your team still sees everyone"). Ask first only on a genuine product choice the user can weigh — who should see the app, what each audience sees — phrased in those terms, never as a manifest or surface decision.
+
 ---
 
 ## Skills
@@ -21,6 +25,9 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-companies` — many-to-many with clients; placeholder companies (excluded from `listCompanies` by default for these apps)
 - `assembly-clients-companies` — REQUIRED when the app stores or scopes data by client or company: scoped tables carry BOTH a `clientId` and a `companyId` column and are filtered on the intersection (never one dimension); a client viewer always has an active `companyId`; `companyIds[]` builds pickers only and `client.companyId` is deprecated
 - `assembly-custom-fields` — workspace-defined fields, multiSelect rules
+<!-- feature:platform-mcp -->
+- `assembly-platform-mcp` — provisioning workspace configuration at build time via the scoped `mcp__platform__` tools: create a custom field the app depends on instead of shipping an app that gates on missing workspace setup. Workspace configuration only — never client-facing data.
+<!-- /feature:platform-mcp -->
 - `assembly-native-resources` — native message channels, forms, portal files/file channels: never hardcode their IDs, discover them at runtime
 - `assembly-mutations` — minimal `requestBody` rule for `update*` calls
 <!-- !feature:notification-settings -->

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 export * from './session-exchange.js';
 export * from './network-capture.js';
+export * from './parent-origin.js';
 export * from './client-companies.js';
 export * from './pagination.js';
 export * from './theme.js';

package/dist/client.js

@@ -7,6 +7,9 @@
 // also runs in the Edge middleware runtime that proxy.ts uses.
 export * from './session-exchange.js';
 export * from './network-capture.js';
+// Self-running on client module load (see the module comment): registers the
+// framing origin with the app-bridge allowlist so custom-domain portals work.
+export * from './parent-origin.js';
 export * from './client-companies.js';
 export * from './pagination.js';
 export * from './theme.js';

package/dist/parent-origin.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolve the origin of the window framing this app.
+ *
+ * Prefers `location.ancestorOrigins` (browser-attested, immune to referrer
+ * policy; Chromium/WebKit) and falls back to `document.referrer` (Firefox).
+ * Returns null outside an iframe or when neither source is available —
+ * e.g. a restrictive Referrer-Policy on the parent in Firefox.
+ */
+export declare function resolveParentOrigin(): string | null;
+/**
+ * Add the framing origin to the bridge's postMessage allowlist.
+ *
+ * Idempotent (the bridge holds origins in a Set) and restricted to https
+ * parents — local development origins are already on the default allowlist,
+ * so an http parent never needs registering.
+ */
+export declare function registerParentOriginWithBridge(): void;

package/dist/parent-origin.js

@@ -0,0 +1,57 @@
+// Registers the app's real framing origin with the app-bridge postMessage
+// allowlist, so the bridge works on workspaces with custom portal domains.
+//
+// The bridge SDK ships a hardcoded origin allowlist (localhost + assembly
+// domains) and silently drops every outgoing and incoming message when the
+// parent origin isn't on it. On a custom-domain portal that kills header CTAs,
+// session-token refresh, and theme sync. Trusting the framing origin here is
+// sound because the proxy already gates who may frame the app at all: its CSP
+// frame-ancestors directive allows only the static assembly domains plus this
+// workspace's own portal URL, and the browser enforces that before any of this
+// bundle runs. Inside the frame, the browser-reported parent origin is
+// therefore always one the platform trusts.
+import { AssemblyBridge } from '@assembly-js/app-bridge';
+/**
+ * Resolve the origin of the window framing this app.
+ *
+ * Prefers `location.ancestorOrigins` (browser-attested, immune to referrer
+ * policy; Chromium/WebKit) and falls back to `document.referrer` (Firefox).
+ * Returns null outside an iframe or when neither source is available —
+ * e.g. a restrictive Referrer-Policy on the parent in Firefox.
+ */
+export function resolveParentOrigin() {
+    if (typeof window === 'undefined')
+        return null;
+    if (window.parent === window)
+        return null;
+    const ancestor = window.location.ancestorOrigins?.[0];
+    if (ancestor)
+        return ancestor;
+    try {
+        const referrer = document.referrer;
+        if (referrer)
+            return new URL(referrer).origin;
+    }
+    catch {
+        // Unparseable referrer — fall through to null.
+    }
+    return null;
+}
+/**
+ * Add the framing origin to the bridge's postMessage allowlist.
+ *
+ * Idempotent (the bridge holds origins in a Set) and restricted to https
+ * parents — local development origins are already on the default allowlist,
+ * so an http parent never needs registering.
+ */
+export function registerParentOriginWithBridge() {
+    const origin = resolveParentOrigin();
+    if (!origin || !origin.startsWith('https://'))
+        return;
+    AssemblyBridge.configure({ additionalOrigins: [origin] });
+}
+// Run on module load: every app's client bundle imports this package (authFetch,
+// network capture), and module evaluation precedes hydration — so the origin is
+// registered before any component's first header/session-token call. Baked app
+// files never call this module directly, which is exactly why it self-runs.
+registerParentOriginWithBridge();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.8-rc.0",
+  "version": "0.0.9",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-custom-fields/SKILL.md

@@ -84,22 +84,3 @@ Send the structured object — a bare string is accepted for backwards compatibi
 - **Clearing a value**: empty array `[]`, not `null` or `undefined`.
 - **Either `key` or `id` works** as the inner option value — use `key` by convention.
 - Same shape applies to `createClient`, `createCompany`, `updateCompany`.
-
-<!-- feature:platform-mcp -->
-## Provisioning fields at build time (platform MCP)
-
-You have a scoped platform MCP server (tool prefix `mcp__platform__`). When the app you are building depends on a custom field the workspace does not have yet — the user asked for "call clients at their phone number" and no Phone-type client field exists — provision it yourself at build time instead of shipping an app that gates on missing workspace config:
-
-```
-mcp__platform__custom_fields with action "list"        — check what exists first
-mcp__platform__custom_fields with action "create"      — create the missing field
-```
-
-Rules:
-
-- **Check before creating** (`list`, match case-insensitively by name) — never create a duplicate of a field that already exists under a slightly different name.
-- **Creating a field does not replace graceful handling.** The app's runtime code must still handle the field being absent or renamed later (discover by name, render a setup hint) — you provision the field the app *starts* with; you don't get to assume it forever.
-- **Never delete fields.** Deletion is not available to you by policy: fields carry data on real client records.
-- **This tool is for workspace configuration only.** Do not reach for `mcp__platform__*` to create clients, send messages/notifications/invoices, or touch any client-facing data — those denials are enforced server-side and the attempt wastes a turn.
-- Tell the user in chat, in product terms, when you create a field ("I added a Phone number field to your client records so the app can call them").
-<!-- /feature:platform-mcp -->

package/skills/assembly-platform-mcp/SKILL.md

@@ -0,0 +1,23 @@
+<!-- feature:platform-mcp -->
+---
+name: assembly-platform-mcp
+description: Use when the app you are building depends on workspace configuration that does not exist yet — most commonly a custom field on clients or companies (the user asked for "call clients at their phone number" and no Phone-type client field exists). You have a scoped platform MCP server (tool prefix mcp__platform__) for provisioning that configuration at build time instead of shipping an app that gates on missing workspace setup. Workspace configuration only — never client-facing data (no creating clients, sending messages, notifications, or invoices).
+---
+
+## Provisioning custom fields at build time
+
+You have a scoped platform MCP server (tool prefix `mcp__platform__`). When the app you are building depends on a custom field the workspace does not have yet — the user asked for "call clients at their phone number" and no Phone-type client field exists — provision it yourself at build time instead of shipping an app that gates on missing workspace config:
+
+```
+mcp__platform__custom_fields with action "list"        — check what exists first
+mcp__platform__custom_fields with action "create"      — create the missing field
+```
+
+Rules:
+
+- **Check before creating** (`list`, match case-insensitively by name) — never create a duplicate of a field that already exists under a slightly different name.
+- **Creating a field does not replace graceful handling.** The app's runtime code must still handle the field being absent or renamed later (discover by name, render a setup hint — see the assembly-custom-fields skill for the runtime contract) — you provision the field the app *starts* with; you don't get to assume it forever.
+- **Never delete fields.** Deletion is not available to you by policy: fields carry data on real client records.
+- **This tool is for workspace configuration only.** Do not reach for `mcp__platform__*` to create clients, send messages/notifications/invoices, or touch any client-facing data — those denials are enforced server-side and the attempt wastes a turn.
+- Tell the user in chat, in product terms, when you create a field ("I added a Phone number field to your client records so the app can call them").
+<!-- /feature:platform-mcp -->