@elytracms/studio 0.0.93 → 0.0.95

package/convex/role-policy.test.ts

@@ -0,0 +1,315 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import { makeFunctionReference } from 'convex/server'
+import type { FunctionReference } from 'convex/server'
+import type { GenericId } from 'convex/values'
+import {
+  ROLE_POLICY_ENV,
+  defaultRolePolicy,
+  rolePolicyFingerprint,
+  serializeRolePolicy,
+} from '@elytracms/core/persistence'
+import type { RolePolicy } from '@elytracms/core/persistence'
+import { resolveProject } from '@elytracms/core/studio-core'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import { gateSessionCreation } from './auth'
+import { requireCapability } from './guard'
+import { deployedRolePolicy } from './roles'
+import schema from './schema'
+
+/**
+ * EC-605 — the Convex trust boundary reads the project's role policy from the copy the
+ * CLI provisions into `ELYTRA_ROLE_POLICY`, and only that copy.
+ *
+ * The REAL `members` / `invites` / `roles` handlers and the REAL guard + integrity floor
+ * run on convex-test's in-memory backend; the env is stubbed per test (set, unset,
+ * malformed). Two member rows hold DIFFERENT custom roles, so a decision that silently
+ * fell back to the default policy (where both roles are unknown) is visible.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const ISSUER = 'https://convex.test'
+
+/** The fourth-role proof: a `reviewer` that reads, between viewer and editor. */
+const FOUR_ROLE: RolePolicy = {
+  roles: [
+    { id: 'viewer', label: 'Viewer', capabilities: ['content.read'] },
+    { id: 'reviewer', label: 'Reviewer', capabilities: ['content.read'] },
+    { id: 'editor', label: 'Editor', capabilities: ['content.read', 'content.write'] },
+    { id: 'admin', label: 'Admin', capabilities: ['content.read', 'content.write', 'project.administer'] },
+  ],
+}
+
+/** An administering role BELOW the strongest — what the floor's rank invariant guards. */
+const RANKED: RolePolicy = {
+  roles: [
+    { id: 'author', capabilities: ['content.read', 'content.write'] },
+    { id: 'manager', capabilities: ['content.read', 'content.write', 'project.administer'] },
+    { id: 'owner', capabilities: ['content.read', 'content.write', 'project.administer'] },
+  ],
+}
+
+const membersSet = makeFunctionReference<'mutation'>('members:set')
+const membersList = makeFunctionReference<'query'>('members:list')
+const invitesCreate = makeFunctionReference<'mutation'>('invites:create')
+const fingerprintQuery = makeFunctionReference<'query'>('roles:fingerprint')
+
+const NOW = '2026-10-26T00:00:00.000Z'
+
+async function backendWith(rows: Array<{ userId: string; role: string }>) {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    for (const row of rows) {
+      await ctx.db.insert('members', { ...row, createdAt: NOW, updatedAt: NOW })
+    }
+  })
+  return t
+}
+
+const as = (t: ReturnType<typeof convexTest>, userId: string) =>
+  t.withIdentity({ subject: userId, issuer: ISSUER })
+
+/** Run the guard itself as `userId` — the one primitive every engine handler gates on. */
+async function canDo(
+  t: ReturnType<typeof convexTest>,
+  userId: string,
+  capability: 'content.read' | 'content.write' | 'project.administer',
+): Promise<boolean> {
+  try {
+    await as(t, userId).run((ctx) => requireCapability(ctx, capability))
+    return true
+  } catch {
+    return false
+  }
+}
+
+beforeEach(() => {
+  vi.unstubAllEnvs()
+})
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+describe('the deployed role policy (EC-605) — absent → the default, byte-identical', () => {
+  it('reads the default policy when ELYTRA_ROLE_POLICY is unset or blank', () => {
+    expect(deployedRolePolicy({})).toBe(defaultRolePolicy)
+    expect(deployedRolePolicy({ [ROLE_POLICY_ENV]: '  ' })).toBe(defaultRolePolicy)
+  })
+
+  it('keeps the historical tiers with no env: viewer reads, editor writes, admin administers', async () => {
+    const t = await backendWith([
+      { userId: 'u_viewer', role: 'viewer' },
+      { userId: 'u_editor', role: 'editor' },
+      { userId: 'u_admin', role: 'admin' },
+    ])
+    expect(await canDo(t, 'u_viewer', 'content.read')).toBe(true)
+    expect(await canDo(t, 'u_viewer', 'content.write')).toBe(false)
+    expect(await canDo(t, 'u_editor', 'content.write')).toBe(true)
+    expect(await canDo(t, 'u_editor', 'project.administer')).toBe(false)
+    expect(await canDo(t, 'u_admin', 'project.administer')).toBe(true)
+  })
+
+  it('refuses to store a role the default policy does not declare (members:set, invites:create)', async () => {
+    const t = await backendWith([{ userId: 'u_admin', role: 'admin' }])
+    await expect(
+      as(t, 'u_admin').mutation(membersSet, { userId: 'u_x', role: 'reviewer', createdAt: NOW, updatedAt: NOW }),
+    ).rejects.toThrow(/invalid-role: role "reviewer" is not declared/)
+    await expect(
+      as(t, 'u_admin').mutation(invitesCreate, {
+        email: 'x@example.com',
+        role: 'reviewer',
+        createdAt: NOW,
+        updatedAt: NOW,
+      }),
+    ).rejects.toThrow(/invalid-role/)
+    // Control: a declared role is stored.
+    const stored = await as(t, 'u_admin').mutation(membersSet, {
+      userId: 'u_x',
+      role: 'editor',
+      createdAt: NOW,
+      updatedAt: NOW,
+    })
+    expect(stored).toMatchObject({ userId: 'u_x', role: 'editor' })
+  })
+
+  it('answers the default fingerprint, sourced from the default', async () => {
+    const t = convexTest(schema, modules)
+    expect(await t.query(fingerprintQuery, {})).toEqual({
+      status: 'ok',
+      fingerprint: rolePolicyFingerprint(defaultRolePolicy),
+      source: 'default',
+    })
+  })
+})
+
+describe('a provisioned four-role policy — honoured by the guard with two custom-role members', () => {
+  beforeEach(() => {
+    vi.stubEnv(ROLE_POLICY_ENV, serializeRolePolicy(FOUR_ROLE))
+  })
+
+  it('stores the custom role (members:set) and the guard grants by it', async () => {
+    const t = await backendWith([{ userId: 'u_admin', role: 'admin' }])
+    for (const [userId, role] of [
+      ['u_reviewer', 'reviewer'],
+      ['u_editor', 'editor'],
+    ] as const) {
+      const stored = await as(t, 'u_admin').mutation(membersSet, { userId, role, createdAt: NOW, updatedAt: NOW })
+      expect(stored).toMatchObject({ userId, role })
+    }
+    // The reviewer reads (a real handler) but cannot write; the editor writes.
+    expect(await as(t, 'u_reviewer').query(membersList, {})).toHaveLength(3)
+    expect(await canDo(t, 'u_reviewer', 'content.read')).toBe(true)
+    expect(await canDo(t, 'u_reviewer', 'content.write')).toBe(false)
+    expect(await canDo(t, 'u_editor', 'content.write')).toBe(true)
+    expect(await canDo(t, 'u_editor', 'project.administer')).toBe(false)
+  })
+
+  it('control: without the env the same reviewer row grants NOTHING (unknown role fails closed)', async () => {
+    vi.unstubAllEnvs()
+    const t = await backendWith([{ userId: 'u_reviewer', role: 'reviewer' }])
+    expect(await canDo(t, 'u_reviewer', 'content.read')).toBe(false)
+  })
+
+  it('answers the provisioned policy’s fingerprint, sourced from the env', async () => {
+    const t = convexTest(schema, modules)
+    expect(await t.query(fingerprintQuery, {})).toEqual({
+      status: 'ok',
+      fingerprint: rolePolicyFingerprint(FOUR_ROLE),
+      source: 'env',
+    })
+    expect(rolePolicyFingerprint(FOUR_ROLE)).not.toBe(rolePolicyFingerprint(defaultRolePolicy))
+  })
+
+  it('stores a custom role through the production adapter unchanged (no silent viewer floor)', async () => {
+    const t = await backendWith([{ userId: 'u_admin', role: 'admin' }])
+    const asAdmin = as(t, 'u_admin')
+    const client = {
+      query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => asAdmin.query(ref, args ?? {}),
+      mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) =>
+        asAdmin.mutation(ref, args ?? {}),
+    } as unknown as ConvexHttpClient
+    // users:get joins the auth `users` row; give the member an identity row first.
+    const userId = await t.run(async (ctx) => {
+      const id = await ctx.db.insert('users', { email: 'rev@example.com' })
+      return String(id)
+    })
+    const adapter = new ConvexPersistenceAdapter(client, 'role-policy')
+    await adapter.users.saveUser('role-policy', { id: userId, roles: ['reviewer'] })
+    const row = await t.run((ctx) =>
+      ctx.db
+        .query('members')
+        .withIndex('by_user', (q) => q.eq('userId', userId))
+        .first(),
+    )
+    expect(row?.role).toBe('reviewer')
+  })
+})
+
+describe('the integrity floor under a ranked custom policy (an administering role below the strongest)', () => {
+  beforeEach(() => {
+    vi.stubEnv(ROLE_POLICY_ENV, serializeRolePolicy(RANKED))
+  })
+
+  it('a manager assigns roles up to its own rank, never above (members:set and invites:create)', async () => {
+    const t = await backendWith([
+      { userId: 'u_owner', role: 'owner' },
+      { userId: 'u_manager', role: 'manager' },
+    ])
+    const manager = as(t, 'u_manager')
+    await expect(
+      manager.mutation(membersSet, { userId: 'u_new', role: 'author', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'author' })
+    await expect(
+      manager.mutation(membersSet, { userId: 'u_new', role: 'manager', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'manager' })
+    await expect(
+      manager.mutation(membersSet, { userId: 'u_new', role: 'owner', createdAt: NOW, updatedAt: NOW }),
+    ).rejects.toThrow(/cannot assign the “owner” role/)
+    await expect(
+      manager.mutation(invitesCreate, { email: 'boss@example.com', role: 'owner', createdAt: NOW, updatedAt: NOW }),
+    ).rejects.toThrow(/cannot assign the “owner” role/)
+    // Control: the owner (strongest) may invite an owner.
+    await expect(
+      as(t, 'u_owner').mutation(invitesCreate, { email: 'boss@example.com', role: 'owner', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'owner' })
+  })
+
+  it('counts every administering role for "the last administrator" — demoting one of two is allowed, the last is not', async () => {
+    const t = await backendWith([
+      { userId: 'u_owner', role: 'owner' },
+      { userId: 'u_manager', role: 'manager' },
+    ])
+    // Two administrators: the owner demotes the manager to author.
+    await expect(
+      as(t, 'u_owner').mutation(membersSet, { userId: 'u_manager', role: 'author', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'author' })
+    // Now the owner is the last administrator: demoting themselves is refused.
+    await expect(
+      as(t, 'u_owner').mutation(membersSet, { userId: 'u_owner', role: 'manager', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'manager' })
+    await expect(
+      as(t, 'u_owner').mutation(membersSet, { userId: 'u_owner', role: 'author', createdAt: NOW, updatedAt: NOW }),
+    ).rejects.toThrow(/last admin/)
+  })
+
+  it('bootstraps the first user into the strongest role (owner), not a literal "admin"', async () => {
+    const t = convexTest(schema, modules)
+    const userId = await t.run((ctx) => ctx.db.insert('users', { email: 'first@example.com' }))
+    await t.run((ctx) => gateSessionCreation(ctx as never, { userId: userId as GenericId<'users'> }))
+    const row = await t.run((ctx) => ctx.db.query('members').first())
+    expect(row?.role).toBe('owner')
+  })
+})
+
+describe('a malformed or invalid deployed copy throws — never a silent default', () => {
+  it('every guarded function fails, naming ELYTRA_ROLE_POLICY', async () => {
+    vi.stubEnv(ROLE_POLICY_ENV, '{not json')
+    const t = await backendWith([{ userId: 'u_admin', role: 'admin' }])
+    await expect(as(t, 'u_admin').query(membersList, {})).rejects.toThrow(/ELYTRA_ROLE_POLICY is not valid JSON/)
+  })
+
+  it('an invalid policy (no administering role) is refused with the located rule', () => {
+    const invalid = JSON.stringify({ v: 1, roles: [{ id: 'viewer', capabilities: ['content.read'] }] })
+    expect(() => deployedRolePolicy({ [ROLE_POLICY_ENV]: invalid })).toThrow(/No role grants “project.administer”/)
+  })
+
+  it('the fingerprint query answers `invalid` with the reason instead of throwing', async () => {
+    vi.stubEnv(ROLE_POLICY_ENV, '{"v":2,"roles":[]}')
+    const t = convexTest(schema, modules)
+    const answer = (await t.query(fingerprintQuery, {})) as { status: string; detail: string }
+    expect(answer.status).toBe('invalid')
+    expect(answer.detail).toMatch(/ELYTRA_ROLE_POLICY is not a serialised role policy/)
+  })
+
+  it('a changed env is read on the next call (the parse is cached per string, not per process)', () => {
+    const four = serializeRolePolicy(FOUR_ROLE)
+    expect(deployedRolePolicy({ [ROLE_POLICY_ENV]: four }).roles.map((r) => r.id)).toContain('reviewer')
+    expect(deployedRolePolicy({ [ROLE_POLICY_ENV]: serializeRolePolicy(RANKED) }).roles.map((r) => r.id)).toEqual([
+      'author',
+      'manager',
+      'owner',
+    ])
+  })
+})
+
+describe('one declaration, two readers — the config entry reaches the guard through the provisioned copy', () => {
+  it('resolveProject → serializeRolePolicy → ELYTRA_ROLE_POLICY → the guard grants the declared reviewer', async () => {
+    const resolved = resolveProject({
+      name: 'Acme',
+      slug: 'acme',
+      locales: { default: 'en', locales: ['en'] },
+      roles: FOUR_ROLE.roles.map((role) => ({ ...role, capabilities: [...role.capabilities] })),
+    })
+    expect(resolved.ok).toBe(true)
+    if (!resolved.ok) return
+    vi.stubEnv(ROLE_POLICY_ENV, serializeRolePolicy(resolved.project.roles!))
+    const t = await backendWith([{ userId: 'u_reviewer', role: 'reviewer' }])
+    expect(await canDo(t, 'u_reviewer', 'content.read')).toBe(true)
+    expect(await canDo(t, 'u_reviewer', 'content.write')).toBe(false)
+  })
+})

package/convex/roles.ts

@@ -0,0 +1,83 @@
+import {
+  ROLE_POLICY_ENV,
+  defaultRolePolicy,
+  parseRolePolicy,
+  rolePolicyFingerprint,
+} from '@elytracms/core/persistence'
+import type { RolePolicy } from '@elytracms/core/persistence'
+import { query } from './functions'
+
+/**
+ * The role policy this deployment ENFORCES (EC-605) — the Convex trust boundary's
+ * reader of the project's `roles` declaration.
+ *
+ * Convex functions cannot import `elytra.config.ts`, and the nine engine modules that
+ * gate on a capability import `./guard` inside the package, so the declaration reaches
+ * the deployment as a serialised copy in its env: `ELYTRA_ROLE_POLICY`, provisioned by
+ * the `elytra` CLI from the resolved project (`elytra init`, and `elytra build` before
+ * every Convex deploy). `guard.ts`, `authority.ts`, `members.ts`, `invites.ts` and the
+ * first-user bootstrap (`auth.ts`) all read it through {@link deployedRolePolicy}.
+ *
+ * - **Absent (or blank)** → the shipped default policy, byte-identical to before EC-605.
+ * - **Present but malformed or invalid** → THROWS, naming every reason
+ *   (`parseRolePolicy`): every guarded function then fails loudly rather than enforcing
+ *   a policy nobody declared. Never a silent default.
+ *
+ * The env is read per CALL (a provisioned change takes effect without a redeploy) and
+ * the parse is cached per serialised string, so the steady state costs one string
+ * comparison.
+ *
+ * The public {@link fingerprint} query is how a drift between this copy and the config
+ * becomes visible: `elytra doctor` and the studio compare it with the config's own
+ * fingerprint. Consumers reach it through a one-line re-export (`convex/roles.ts`); the
+ * readers above work without it.
+ */
+
+let cached: { readonly serialized: string; readonly policy: RolePolicy } | undefined
+
+/** The deployment env, reached via `globalThis` so this module needs no Node types at runtime. */
+function deploymentEnv(): Record<string, string | undefined> {
+  return (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+}
+
+/**
+ * The deployed role policy: the parsed `ELYTRA_ROLE_POLICY`, or the default when it is
+ * unset. Throws on a malformed or invalid value (see the module comment). `env` is
+ * injectable for tests.
+ */
+export function deployedRolePolicy(env: Record<string, string | undefined> = deploymentEnv()): RolePolicy {
+  const serialized = env[ROLE_POLICY_ENV]
+  if (serialized === undefined || serialized.trim() === '') return defaultRolePolicy
+  if (cached?.serialized === serialized) return cached.policy
+  const policy = parseRolePolicy(serialized)
+  cached = { serialized, policy }
+  return policy
+}
+
+/** What {@link fingerprint} answers — the deployed policy's identity, never its content. */
+export type DeployedRolePolicyFingerprint =
+  | { readonly status: 'ok'; readonly fingerprint: string; readonly source: 'env' | 'default' }
+  | { readonly status: 'invalid'; readonly detail: string }
+
+/**
+ * PUBLIC, unauthenticated: the fingerprint of the role policy this deployment enforces
+ * (`rolePolicyFingerprint` — 16 hex chars over ids, rank and capabilities; labels and
+ * the policy itself never leave the deployment) and whether it comes from
+ * `ELYTRA_ROLE_POLICY` or the default. `elytra doctor` reads it without a session (the
+ * doctor's env rule — names only, values never printed — stands: this is not a value),
+ * and the studio reads it at boot. A malformed or invalid deployed copy answers
+ * `invalid` with the located reasons instead of throwing, so the drift check can say
+ * exactly what is wrong.
+ */
+export const fingerprint = query({
+  args: {},
+  handler: async (): Promise<DeployedRolePolicyFingerprint> => {
+    const env = deploymentEnv()
+    const source = env[ROLE_POLICY_ENV]?.trim() ? 'env' : 'default'
+    try {
+      return { status: 'ok', fingerprint: rolePolicyFingerprint(deployedRolePolicy(env)), source }
+    } catch (error) {
+      return { status: 'invalid', detail: error instanceof Error ? error.message : String(error) }
+    }
+  },
+})

package/convex/schema.ts

@@ -277,6 +277,12 @@ export default defineSchema({
     lqip: v.optional(v.string()),
     /** Schema-driven asset metadata bag (EC-301): alt, copyright, credit, …. */
     meta: v.optional(v.any()),
+    /**
+     * EC-632 — the per-locale values of the asset collection's `localized: true` fields,
+     * `{ [locale]: { [field]: value } }` (the document mechanism beside `meta`). Optional:
+     * every row without one reads its shared `meta`, exactly as before.
+     */
+    localizedMeta: v.optional(v.any()),
     createdAt: v.string(),
     updatedAt: v.string(),
   }).index('by_asset', ['assetId']),
@@ -299,6 +305,36 @@ export default defineSchema({
     updatedAt: v.string(),
   }).index('by_redirect', ['redirectId']),
 
+  /**
+   * The generic RECORD STORE (EC-616) — one row per record of a DECLARED record kind
+   * (`defineRecordKind` in `@elytracms/core/persistence`): the engine's own kinds and
+   * every addon's. `data` holds the kind's columns + its open `meta` bag, validated by
+   * the kind's schema in the write path (`defineRecordFunctions`, `record-functions.ts`)
+   * — the data SHAPE, never project structure (EC-585 1e).
+   *
+   * The index slots are STATIC (a consumer re-exports this schema, so an addon can never
+   * add an index); a kind fills them from its own declared columns: `key1`/`key2` from
+   * its `keys`, `at` from its `time` column (else `createdAt`). The indexes are the
+   * known access paths: one record by id; a kind by time (recent-first lists, a TTL
+   * sweep); by either key + time (submissions by form or by status, newest first); by
+   * both keys + time (an aggregate by day + document).
+   */
+  records: defineTable({
+    kind: v.string(),
+    recordId: v.string(),
+    data: v.any(),
+    key1: v.optional(v.string()),
+    key2: v.optional(v.string()),
+    at: v.string(),
+    createdAt: v.string(),
+    updatedAt: v.string(),
+  })
+    .index('by_kind_record', ['kind', 'recordId'])
+    .index('by_kind_at', ['kind', 'at'])
+    .index('by_kind_key1', ['kind', 'key1', 'at'])
+    .index('by_kind_key2', ['kind', 'key2', 'at'])
+    .index('by_kind_keys', ['kind', 'key1', 'key2', 'at']),
+
   /**
    * Reference index entries (EC-155, vision AD-6) — derived data, recomputed
    * replace-all-for-source on every write. Indexed for efficient lookup in both

package/convex/triggers.ts

@@ -1,5 +1,6 @@
 import { unfoldDocument } from '@elytracms/core/cms-core'
 import type { CmsDocument } from '@elytracms/core/cms-core'
+import { redirectRecordKind } from '@elytracms/core/persistence'
 import { Triggers } from 'convex-helpers/server/triggers'
 import type { DataModel } from './functions'
 import { maintainDocumentReferences, removeDocumentReferences } from './referenceMaintenance'
@@ -33,7 +34,8 @@ import { scheduleRevalidate } from './revalidate'
  *
  * - `cmsDocuments` — only when the live pin (`publishedVersion`) moves
  *   (`publish` / `unpublish`), or a pinned row is deleted (`delete`);
- * - `redirects` (EC-510) — every write (`redirects`; the row IS the live state);
+ * - `records` of the redirect kind (EC-616; EC-510 before it on the `redirects` table) —
+ *   every write (`redirects`; the row IS the live state); no other record kind;
  * - `assets` (EC-579) — every edit and delete (`asset`); a create fires nothing.
  *
  * The snapshot reads one more table, `documentVersions`, but only the version a
@@ -129,6 +131,24 @@ triggers.register('redirects', async (ctx) => {
   await scheduleRevalidate(ctx, { kind: 'redirects' })
 })
 
+/**
+ * The generic record store (EC-616). Of all record kinds, ONLY the engine's redirect
+ * kind is projected onto the live wire (`delivery.ts` reads it through
+ * `loadRedirectEntries`), so only a write to a `redirect` row revalidates — with exactly
+ * the event the legacy `redirects` table fired above (EC-510: every write, the receiver
+ * answers with the sweep). Every other kind — an addon's submissions, analytics rows —
+ * is never on the wire and fires nothing; a kind that starts reaching the snapshot
+ * belongs in this check.
+ *
+ * Since the move, a redirect write is a `records` write; the legacy table's trigger
+ * above still fires for the transitional deletes (a save lifting a legacy-only redirect
+ * deletes its legacy row: two sweeps for that one save, until the migration ran).
+ */
+triggers.register('records', async (ctx, change) => {
+  const kind = (change.newDoc ?? change.oldDoc)?.kind
+  if (kind === redirectRecordKind.kind) await scheduleRevalidate(ctx, { kind: 'redirects' })
+})
+
 /**
  * Asset records (EC-579). The delivery snapshot projects every asset row onto
  * the live wire field by field (url, dimensions, alt, focal point, lqip, the

package/dist/addon.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `@elytracms/studio/addon` — THE public addon API (EC-616, ruling EC-565 § 6b item 2).
+ *
+ * An addon (`@elytracms/forms`, `@elytracms/analytics`, or your own) is an optional
+ * package whose studio half contributes navigation items to a project's
+ * `defineStudio({ sidebar })` — a rail bound to a record kind, or a view with its own
+ * component — and whose backend half is a record kind in the generic record store
+ * (`defineRecordKind` / `adapter.records(kind)` in `@elytracms/core/persistence`, its
+ * Convex functions from `defineRecordFunctions` in `@elytracms/studio/convex/
+ * record-functions`). Everything an addon's studio code touches is exported HERE; the
+ * studio's internals (`lib/*`, `components/*`) are not part of the published package.
+ * `@elytracms/studio/ui` stays the primitive set (Button, Panel, Text, …).
+ *
+ * ## The chrome contract
+ *
+ * The SHELL draws the top bar, the breadcrumb (its section crumb is the view's `label`;
+ * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail with its issues
+ * foot (findings contributed with {@link useNavIssues}, or always-on through a view's
+ * `useIssues`), the banners and the theme. A VIEW owns the whole scrollable content area
+ * under it — including its own title header: the shell adds no frame, title or padding.
+ * A view reaches the studio through its {@link AppViewContext}: the project, its deep
+ * link and search, the operations client (every read and write goes through the one
+ * authorized chokepoint), the query hooks over the one cache, the content locale, and
+ * the signed-in user with their role.
+ *
+ * ## The two navigation items
+ *
+ * ```tsx
+ * import { nav } from '@elytracms/studio/addon'
+ * import { submissionRecordKind } from './kinds'
+ *
+ * // a rail bound to a record kind — the portable list/edit surfaces, no component to write
+ * nav.rail(submissionRecordKind, { label: 'Submissions' })
+ * // a custom component — the whole content area is yours
+ * nav.view({ id: 'forms-stats', label: 'Form stats', render: (ctx) => <Stats ctx={ctx} /> })
+ * ```
+ */
+export { nav } from './components/app-views/default-modules.js';
+export type { CustomViewConfig, RailViewConfig, BuiltinViewConfig, } from './components/app-views/default-modules.js';
+export type { AppViewContext, AppViewDeepLink, AppViewModule, AppViewQueryHooks, NavIssuesHook, NavPermission, NavPermissionContext, SidebarNode, SidebarViewNode, } from './components/app-views/module.js';
+/** A record rail's pieces, for an addon composing its own view around one. */
+export { RECORD_RAIL_CAPABILITIES, RecordRailModule, RecordRailProvider, useRecordCollectionViewSource, useRecordList, useRecordRail, } from './components/records/record-rail.js';
+export type { RecordRailModuleProps, RecordRailPaths, RecordRailStore } from './components/records/record-rail.js';
+export { lensDocumentToRecordWrite, recordLensDef, recordToLensDocument } from './components/records/record-lens.js';
+/** The portable list/edit surfaces over any source, and the scaffold that assembles one. */
+export { CollectionViewSurface } from './components/collection-view/collection-view-surface.js';
+export { assembleRailViewSource, metaBagProjection, normalizeOkResult, useRailViewSource, } from './components/rail-view-source.js';
+export type { OkResult, RailAdapter } from './components/rail-view-source.js';
+export type { CollectionViewCapabilities, CollectionViewSource, FieldAccess, } from './lib/collection-view/collection-view-source.js';
+export { useOperationCache, useOperationQuery } from './lib/query/index.js';
+export type { OperationCache, ReadState, UseOperationQueryOptions } from './lib/query/index.js';
+export { useStudioLocale } from './lib/locale/index.js';
+export type { StudioLocale } from './lib/locale/index.js';
+export { useSetBreadcrumb } from './components/breadcrumb-context.js';
+export type { BreadcrumbItem } from './components/breadcrumb-context.js';
+export { useNavIssues } from './components/nav-issues-registry.js';
+export type { NavIssue } from './components/nav-issues-registry.js';
+/** A pane in the document editor's inspector — `defineStudio({ documentPanes: [documentPane({ … })] })`. */
+export { documentPane } from './components/inspector/document-panes.js';
+export type { DocumentPane, DocumentPaneContext } from './components/inspector/document-panes.js';
+/**
+ * The portable edit shell alone (AD-19), with its form-column appendix seam (EC-396): an addon
+ * that assembles its own source (`useRailViewSource`) renders one record's detail with
+ * read-only sections below the editable fields — the forms inbox shows a submission's answers,
+ * files and delivery log there.
+ */
+export { PortableDetailEditor } from './components/cms/detail-editor.js';
+/** The one query key of a kind's records in a project — patch it after a write (`useOperationCache`). */
+export { recordListKey } from './components/records/record-rail.js';
+/** Resolve a `LocalizedString` (`'Text'` or `{ en, de, … }`) in the studio's UI language. */
+export { useLabel } from './lib/i18n/index.js';

package/dist/addon.js

@@ -0,0 +1,67 @@
+/**
+ * `@elytracms/studio/addon` — THE public addon API (EC-616, ruling EC-565 § 6b item 2).
+ *
+ * An addon (`@elytracms/forms`, `@elytracms/analytics`, or your own) is an optional
+ * package whose studio half contributes navigation items to a project's
+ * `defineStudio({ sidebar })` — a rail bound to a record kind, or a view with its own
+ * component — and whose backend half is a record kind in the generic record store
+ * (`defineRecordKind` / `adapter.records(kind)` in `@elytracms/core/persistence`, its
+ * Convex functions from `defineRecordFunctions` in `@elytracms/studio/convex/
+ * record-functions`). Everything an addon's studio code touches is exported HERE; the
+ * studio's internals (`lib/*`, `components/*`) are not part of the published package.
+ * `@elytracms/studio/ui` stays the primitive set (Button, Panel, Text, …).
+ *
+ * ## The chrome contract
+ *
+ * The SHELL draws the top bar, the breadcrumb (its section crumb is the view's `label`;
+ * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail with its issues
+ * foot (findings contributed with {@link useNavIssues}, or always-on through a view's
+ * `useIssues`), the banners and the theme. A VIEW owns the whole scrollable content area
+ * under it — including its own title header: the shell adds no frame, title or padding.
+ * A view reaches the studio through its {@link AppViewContext}: the project, its deep
+ * link and search, the operations client (every read and write goes through the one
+ * authorized chokepoint), the query hooks over the one cache, the content locale, and
+ * the signed-in user with their role.
+ *
+ * ## The two navigation items
+ *
+ * ```tsx
+ * import { nav } from '@elytracms/studio/addon'
+ * import { submissionRecordKind } from './kinds'
+ *
+ * // a rail bound to a record kind — the portable list/edit surfaces, no component to write
+ * nav.rail(submissionRecordKind, { label: 'Submissions' })
+ * // a custom component — the whole content area is yours
+ * nav.view({ id: 'forms-stats', label: 'Form stats', render: (ctx) => <Stats ctx={ctx} /> })
+ * ```
+ */
+// --- Navigation items and the view contract --------------------------------------------
+export { nav } from './components/app-views/default-modules.js';
+// --- Rails: a record kind, or your own source -------------------------------------------
+/** A record rail's pieces, for an addon composing its own view around one. */
+export { RECORD_RAIL_CAPABILITIES, RecordRailModule, RecordRailProvider, useRecordCollectionViewSource, useRecordList, useRecordRail, } from './components/records/record-rail.js';
+export { lensDocumentToRecordWrite, recordLensDef, recordToLensDocument } from './components/records/record-lens.js';
+/** The portable list/edit surfaces over any source, and the scaffold that assembles one. */
+export { CollectionViewSurface } from './components/collection-view/collection-view-surface.js';
+export { assembleRailViewSource, metaBagProjection, normalizeOkResult, useRailViewSource, } from './components/rail-view-source.js';
+// --- Hooks: the cache, the locale, the breadcrumb, the rail foot -------------------------
+export { useOperationCache, useOperationQuery } from './lib/query/index.js';
+export { useStudioLocale } from './lib/locale/index.js';
+export { useSetBreadcrumb } from './components/breadcrumb-context.js';
+export { useNavIssues } from './components/nav-issues-registry.js';
+// --- The document editor: contributed inspector panes (EC-618) ---------------------------
+/** A pane in the document editor's inspector — `defineStudio({ documentPanes: [documentPane({ … })] })`. */
+export { documentPane } from './components/inspector/document-panes.js';
+// --- EC-613 (the forms addon): an own source's edit shell, its list key, the UI language -----
+/**
+ * The portable edit shell alone (AD-19), with its form-column appendix seam (EC-396): an addon
+ * that assembles its own source (`useRailViewSource`) renders one record's detail with
+ * read-only sections below the editable fields — the forms inbox shows a submission's answers,
+ * files and delivery log there.
+ */
+export { PortableDetailEditor } from './components/cms/detail-editor.js';
+/** The one query key of a kind's records in a project — patch it after a write (`useOperationCache`). */
+export { recordListKey } from './components/records/record-rail.js';
+/** Resolve a `LocalizedString` (`'Text'` or `{ en, de, … }`) in the studio's UI language. */
+export { useLabel } from './lib/i18n/index.js';
+//# sourceMappingURL=addon.js.map

package/dist/addon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon.js","sourceRoot":"","sources":["../src/addon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,0FAA0F;AAE1F,OAAO,EAAE,GAAG,EAAE,MAAM,wCAAwC,CAAA;AAkB5D,2FAA2F;AAE3F,8EAA8E;AAC9E,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,6BAA6B,EAC7B,aAAa,EACb,aAAa,GACd,MAAM,kCAAkC,CAAA;AAEzC,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAEjH,4FAA4F;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAA;AAC5F,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,+BAA+B,CAAA;AAQtC,4FAA4F;AAE5F,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAElE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAElE,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AAG/D,4FAA4F;AAE5F,4GAA4G;AAC5G,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AAGpE,gGAAgG;AAEhG;;;;;GAKG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAA;AACrE,yGAAyG;AACzG,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAChE,6FAA6F;AAC7F,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA","sourcesContent":["/**\n * `@elytracms/studio/addon` — THE public addon API (EC-616, ruling EC-565 § 6b item 2).\n *\n * An addon (`@elytracms/forms`, `@elytracms/analytics`, or your own) is an optional\n * package whose studio half contributes navigation items to a project's\n * `defineStudio({ sidebar })` — a rail bound to a record kind, or a view with its own\n * component — and whose backend half is a record kind in the generic record store\n * (`defineRecordKind` / `adapter.records(kind)` in `@elytracms/core/persistence`, its\n * Convex functions from `defineRecordFunctions` in `@elytracms/studio/convex/\n * record-functions`). Everything an addon's studio code touches is exported HERE; the\n * studio's internals (`lib/*`, `components/*`) are not part of the published package.\n * `@elytracms/studio/ui` stays the primitive set (Button, Panel, Text, …).\n *\n * ## The chrome contract\n *\n * The SHELL draws the top bar, the breadcrumb (its section crumb is the view's `label`;\n * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail with its issues\n * foot (findings contributed with {@link useNavIssues}, or always-on through a view's\n * `useIssues`), the banners and the theme. A VIEW owns the whole scrollable content area\n * under it — including its own title header: the shell adds no frame, title or padding.\n * A view reaches the studio through its {@link AppViewContext}: the project, its deep\n * link and search, the operations client (every read and write goes through the one\n * authorized chokepoint), the query hooks over the one cache, the content locale, and\n * the signed-in user with their role.\n *\n * ## The two navigation items\n *\n * ```tsx\n * import { nav } from '@elytracms/studio/addon'\n * import { submissionRecordKind } from './kinds'\n *\n * // a rail bound to a record kind — the portable list/edit surfaces, no component to write\n * nav.rail(submissionRecordKind, { label: 'Submissions' })\n * // a custom component — the whole content area is yours\n * nav.view({ id: 'forms-stats', label: 'Form stats', render: (ctx) => <Stats ctx={ctx} /> })\n * ```\n */\n\n// --- Navigation items and the view contract --------------------------------------------\n\nexport { nav } from './components/app-views/default-modules'\nexport type {\n  CustomViewConfig,\n  RailViewConfig,\n  BuiltinViewConfig,\n} from './components/app-views/default-modules'\nexport type {\n  AppViewContext,\n  AppViewDeepLink,\n  AppViewModule,\n  AppViewQueryHooks,\n  NavIssuesHook,\n  NavPermission,\n  NavPermissionContext,\n  SidebarNode,\n  SidebarViewNode,\n} from './components/app-views/module'\n\n// --- Rails: a record kind, or your own source -------------------------------------------\n\n/** A record rail's pieces, for an addon composing its own view around one. */\nexport {\n  RECORD_RAIL_CAPABILITIES,\n  RecordRailModule,\n  RecordRailProvider,\n  useRecordCollectionViewSource,\n  useRecordList,\n  useRecordRail,\n} from './components/records/record-rail'\nexport type { RecordRailModuleProps, RecordRailPaths, RecordRailStore } from './components/records/record-rail'\nexport { lensDocumentToRecordWrite, recordLensDef, recordToLensDocument } from './components/records/record-lens'\n\n/** The portable list/edit surfaces over any source, and the scaffold that assembles one. */\nexport { CollectionViewSurface } from './components/collection-view/collection-view-surface'\nexport {\n  assembleRailViewSource,\n  metaBagProjection,\n  normalizeOkResult,\n  useRailViewSource,\n} from './components/rail-view-source'\nexport type { OkResult, RailAdapter } from './components/rail-view-source'\nexport type {\n  CollectionViewCapabilities,\n  CollectionViewSource,\n  FieldAccess,\n} from './lib/collection-view/collection-view-source'\n\n// --- Hooks: the cache, the locale, the breadcrumb, the rail foot -------------------------\n\nexport { useOperationCache, useOperationQuery } from './lib/query'\nexport type { OperationCache, ReadState, UseOperationQueryOptions } from './lib/query'\nexport { useStudioLocale } from './lib/locale'\nexport type { StudioLocale } from './lib/locale'\nexport { useSetBreadcrumb } from './components/breadcrumb-context'\nexport type { BreadcrumbItem } from './components/breadcrumb-context'\nexport { useNavIssues } from './components/nav-issues-registry'\nexport type { NavIssue } from './components/nav-issues-registry'\n\n// --- The document editor: contributed inspector panes (EC-618) ---------------------------\n\n/** A pane in the document editor's inspector — `defineStudio({ documentPanes: [documentPane({ … })] })`. */\nexport { documentPane } from './components/inspector/document-panes'\nexport type { DocumentPane, DocumentPaneContext } from './components/inspector/document-panes'\n\n// --- EC-613 (the forms addon): an own source's edit shell, its list key, the UI language -----\n\n/**\n * The portable edit shell alone (AD-19), with its form-column appendix seam (EC-396): an addon\n * that assembles its own source (`useRailViewSource`) renders one record's detail with\n * read-only sections below the editable fields — the forms inbox shows a submission's answers,\n * files and delivery log there.\n */\nexport { PortableDetailEditor } from './components/cms/detail-editor'\n/** The one query key of a kind's records in a project — patch it after a write (`useOperationCache`). */\nexport { recordListKey } from './components/records/record-rail'\n/** Resolve a `LocalizedString` (`'Text'` or `{ en, de, … }`) in the studio's UI language. */\nexport { useLabel } from './lib/i18n'\n"]}