@elytracms/studio 0.0.97 → 0.0.99

package/convex/prototype-key.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import type { FunctionReference } from 'convex/server'
+import type { CmsDocument, CollectionDef } from '@elytracms/core/cms-core'
+import { createOperations } from '@elytracms/core/operations'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import schema from './schema'
+
+/**
+ * EC-684 (Codex round 4, F27) — the `convex-parity` measurement the refusal rests on, and the refusal
+ * itself over the production `ConvexPersistenceAdapter` (its client a call-through onto convex-test's
+ * REAL `cms.ts` mutations — the wiring of `depth-codec-lookalike.test.ts`).
+ *
+ * 1. Re-measured (Codex measured it in `codec-own-keys.convex.test.ts`): the Convex value converters
+ *    rebuild objects by assignment (`convex/src/values/value.ts` `jsonToConvex` / `convexToJsonInternal`),
+ *    so an own `__proto__` key written straight through the adapter — past the operations layer — is
+ *    lost before any sink, at the top level of `values` and nested. The known-positive control: an
+ *    ordinary own key on the same path survives, so the instrument CAN see a key survive.
+ * 2. So the in-memory store keeping the key would be drift; the operations layer refuses it on the raw
+ *    input, located, in this store too, and nothing is written.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+const P = 'site'
+const ADMIN = 'user_admin'
+const AT = '2026-10-28T12:00:00.000Z'
+
+const collections: CollectionDef[] = [
+  { id: 'post', kind: 'document', fields: [{ name: 'payload', type: 'object', multiple: false, fields: [] }] },
+]
+
+interface Backend {
+  query: (ref: FunctionReference<'query'>, args: Record<string, unknown>) => Promise<unknown>
+  mutation: (ref: FunctionReference<'mutation'>, args: Record<string, unknown>) => Promise<unknown>
+}
+
+function asAdapterClient(backend: Backend): ConvexHttpClient {
+  return {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => backend.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => backend.mutation(ref, args ?? {}),
+  } as unknown as ConvexHttpClient
+}
+
+async function harness() {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: ADMIN, role: 'admin', createdAt: AT, updatedAt: AT })
+  })
+  const adapter = new ConvexPersistenceAdapter(asAdapterClient(t.withIdentity({ subject: ADMIN, issuer: 'https://convex.test' })), P)
+  const ops = createOperations({ adapter, collections: () => collections, validateDocument: () => [] })
+  const rows = async () => t.run(async (ctx) => (await ctx.db.query('cmsDocuments').collect()).map((row) => row.docId))
+  return { adapter, ops, rows }
+}
+
+const parse = <T = Record<string, unknown>>(json: string): T => JSON.parse(json) as T
+const ownProto = (value: unknown) => typeof value === 'object' && value !== null && Object.hasOwn(value, '__proto__')
+
+describe('EC-684 on Convex — an own `__proto__` key', () => {
+  it('re-measured: written straight through the adapter (past operations), Convex loses it before the sink — CONTROL: an ordinary own key survives', async () => {
+    const { adapter } = await harness()
+    const document = parse<CmsDocument>('{"collection":"post","id":"direct","values":{"__proto__":{"text":"TOP"},"payload":{"__proto__":{"text":"NESTED"},"ordinary":{"text":"KEEP"}}}}')
+    expect(ownProto(document.values)).toBe(true)
+    expect(ownProto(document.values.payload)).toBe(true)
+    await adapter.cms.replaceDocument(P, document, { ifAbsent: true })
+    const stored = (await adapter.cms.getDocument(P, { collection: 'post', id: 'direct' })).document
+    expect((stored.values.payload as Record<string, unknown>).ordinary).toEqual({ text: 'KEEP' })
+    expect(ownProto(stored.values)).toBe(false)
+    expect(ownProto(stored.values.payload)).toBe(false)
+  })
+
+  it('through the operations layer it is refused on the raw input, located — and nothing reaches the store', async () => {
+    const { ops, rows } = await harness()
+    const values = parse('{"__proto__":{"text":"TOP"},"payload":{"__proto__":{"text":"NESTED"}}}')
+    const result = await ops.documents.replace({ projectId: P, document: { collection: 'post', id: 'refused', values }, precondition: { ifAbsent: true } })
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.error.code).toBe('validation')
+    expect(result.error.code === 'validation' ? result.error.issues.map((issue) => [issue.code, issue.path]) : []).toEqual([
+      ['prototype-key', ['document', 'values', '__proto__']],
+      ['prototype-key', ['document', 'values', 'payload', '__proto__']],
+    ])
+    expect(await rows()).toEqual([])
+    // CONTROL: the same write without the key goes through.
+    const plain = await ops.documents.replace({ projectId: P, document: { collection: 'post', id: 'plain', values: { payload: { text: 'x' } } }, precondition: { ifAbsent: true } })
+    expect(plain.ok).toBe(true)
+    expect(await rows()).toEqual(['plain'])
+  })
+})

package/convex/records-column-transform.convex.test.ts

@@ -0,0 +1,147 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import type { FunctionReference } from 'convex/server'
+import { z } from 'zod'
+import { z as newerZod } from 'zod-copy-newer'
+import { z as olderZod } from 'zod-copy-older'
+import { createOperations } from '@elytracms/core/operations'
+import { defineRecordKind } from '@elytracms/core/persistence'
+import type { AnyRecordKind, RecordColumnSchema } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
+
+/**
+ * EC-694 (Codex round 5 F31), the Convex half — a record column's transform runs ONCE per write,
+ * in the generated `save` mutation's transaction (`defineRecordFunctions(kind).save` →
+ * `saveRecord` → `resolveRecordSave`, the one parse EC-682 keeps on the Convex side), whether the
+ * write comes straight through the adapter's repository or through `operations.records(kind)`.
+ *
+ * Before: the operations parsed the write and sent the PARSED values over the wire, where the
+ * mutation parsed them again — `seed!!` stored with `ok: true`, and a type-changing column
+ * (`string → length`) refused. Measured red on the wave base 21678336: 12 of 12. Now the
+ * operations judge the columns and send the caller's values as sent.
+ *
+ * The three copies are real zod releases (the engine's own 4.4.3; the aliased devDependencies
+ * `zod-copy-older` 4.1.13 and `zod-copy-newer` 4.6.7). The client is the real
+ * `ConvexPersistenceAdapter` over convex-test, signed in as an editor member — the probe's
+ * wiring (`tasks/codex-review-2026-10-28-r5/record-transform.convex.test.ts`).
+ */
+
+type Vendor = typeof z
+const COPIES = [
+  ['own', z],
+  ['older', olderZod as unknown as Vendor],
+  ['newer', newerZod as unknown as Vendor],
+] as const
+const WRAPPERS = ['required', 'optional', 'default'] as const
+type Wrapper = (typeof WRAPPERS)[number]
+
+const exclaimed = (vendor: Vendor, wrapper: Wrapper) => {
+  const inner = vendor.string().transform((value) => `${value}!`)
+  return wrapper === 'optional' ? inner.optional() : wrapper === 'default' ? inner.default('safe!') : inner
+}
+const lengthOf = (vendor: Vendor) => vendor.string().transform((value) => value.length)
+const capitalised = (name: string) => `${name.charAt(0).toUpperCase()}${name.slice(1)}`
+
+/** One kind per case, each in its own Convex module (Convex addresses a kind's functions by module). */
+function kindFor(name: string, fields: Record<string, unknown>): AnyRecordKind {
+  return defineRecordKind({ kind: name, module: `${name}s`, fields: fields as Record<string, RecordColumnSchema> })
+}
+
+const EXCLAIMED = COPIES.flatMap(([copy, vendor]) =>
+  WRAPPERS.map((wrapper) => ({ copy, wrapper, column: exclaimed(vendor, wrapper), kind: kindFor(`${copy}${capitalised(wrapper)}Text`, { text: exclaimed(vendor, wrapper) }) })),
+)
+const LENGTHS = COPIES.map(([copy, vendor]) => ({ copy, column: lengthOf(vendor), kind: kindFor(`${copy}Count`, { count: lengthOf(vendor) }) }))
+const PLAIN = kindFor('plainText', { text: z.string() })
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+  ...Object.fromEntries(
+    [...EXCLAIMED.map((row) => row.kind), ...LENGTHS.map((row) => row.kind), PLAIN].map((kind) => [
+      `./${kind.module}.ts`,
+      async () => defineRecordFunctions(kind),
+    ]),
+  ),
+}
+
+const PROJECT = 'site'
+const STAMP = '2026-10-28T00:00:00.000Z'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(STAMP)
+})
+afterEach(() => vi.useRealTimers())
+
+/** The real client adapter over convex-test, as a signed-in editor; and the operations over it. */
+async function connected() {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: 'editor', role: 'editor', createdAt: STAMP, updatedAt: STAMP })
+  })
+  const editor = t.withIdentity({ subject: 'editor', issuer: 'https://convex.test' })
+  const client = {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => editor.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => editor.mutation(ref, args ?? {}),
+  } as unknown as ConvexHttpClient
+  const adapter = new ConvexPersistenceAdapter(client, PROJECT)
+  const ops = createOperations({ adapter, collections: () => [], validateDocument: () => [] })
+  return { t, adapter, ops }
+}
+
+describe.each(EXCLAIMED)('EC-694 — Convex, a transforming column of the $copy zod copy, $wrapper', ({ column, kind }) => {
+  it('the operations store what the repository stores (`seed!`, then `edit!`) — the transform runs once', async () => {
+    // Controls (pass with the defect present and absent): the column transforms once, and so
+    // does the repository through the same mutation — the value both paths must agree with.
+    expect((column as unknown as z.ZodType).safeParse('seed')).toMatchObject({ success: true, data: 'seed!' })
+    const { adapter, ops } = await connected()
+    const direct = adapter.records(kind)
+    expect(await direct.save(PROJECT, { id: 'direct', text: 'seed' })).toMatchObject({ text: 'seed!' })
+
+    // The defect row: through the operations, create then edit.
+    const records = ops.records(kind)
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', text: 'seed' })).toMatchObject({ ok: true, value: { text: 'seed!' } })
+    expect((await direct.get(PROJECT, 'viaops')).text).toBe('seed!')
+    expect(await direct.save(PROJECT, { id: 'direct', text: 'edit' })).toMatchObject({ text: 'edit!' })
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', text: 'edit' })).toMatchObject({ ok: true, value: { text: 'edit!' } })
+    expect((await direct.get(PROJECT, 'viaops')).text).toBe('edit!')
+  })
+})
+
+describe.each(LENGTHS)('EC-694 — Convex, a type-changing column of the $copy zod copy', ({ column, kind }) => {
+  it('a value the column accepts is stored through the operations, as through the repository (4)', async () => {
+    expect((column as unknown as z.ZodType).safeParse('seed')).toMatchObject({ success: true, data: 4 })
+    const { adapter, ops } = await connected()
+    const direct = adapter.records(kind)
+    expect(await direct.save(PROJECT, { id: 'direct', count: 'seed' })).toMatchObject({ count: 4 })
+
+    const records = ops.records(kind)
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', count: 'seed' })).toMatchObject({ ok: true, value: { count: 4 } })
+    expect((await direct.get(PROJECT, 'viaops')).count).toBe(4)
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', count: 'edited' })).toMatchObject({ ok: true, value: { count: 6 } })
+  })
+})
+
+describe('EC-694 — Convex, what the operations send', () => {
+  it('a refused value is the operation’s own refusal: no mutation runs, nothing stored', async () => {
+    const { t, ops } = await connected()
+    const kind = EXCLAIMED[0]!.kind
+    const refused = await ops.records(kind).save({ projectId: PROJECT, id: 'refused', text: 42 as never })
+    expect(refused).toMatchObject({ ok: false, error: { code: 'validation', message: `Input for “${kind.module}.save” is invalid.` } })
+    expect(await t.run(async (ctx) => ctx.db.query('records').collect())).toEqual([])
+  })
+
+  // A plain column: green before EC-694 too; it fails if the caller's whole input were sent,
+  // because the mutation's argument validator refuses a key it does not declare.
+  it('only the write schema’s keys cross the wire: an undeclared key stays behind (create and edit)', async () => {
+    const { ops } = await connected()
+    const records = ops.records(PLAIN)
+    expect(await records.save({ projectId: PROJECT, id: 'r', text: 'seed', stray: 1 } as never)).toMatchObject({ ok: true, value: { text: 'seed' } })
+    const edited = await records.save({ projectId: PROJECT, id: 'r', text: 'edit', stray: 1 } as never)
+    expect(edited).toMatchObject({ ok: true, value: { text: 'edit', projectId: PROJECT } })
+    expect(edited.ok && 'stray' in edited.value).toBe(false)
+  })
+})

package/convex/records-zod-refinements.convex.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { z } from 'zod'
+import { z as newerZod } from 'zod-copy-newer'
+import { z as olderZod } from 'zod-copy-older'
+import { defineRecordKind } from '@elytracms/core/persistence'
+import type { AnyRecordKind, RecordColumnSchema } from '@elytracms/core/persistence'
+import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
+
+/**
+ * EC-682 (Codex round 4 F24, a regression of 0.0.97) — the generated Convex record functions
+ * (`defineRecordFunctions(kind).save` → `saveRecord` → `resolveRecordSave`, in the transaction)
+ * for a kind whose column carries a refinement on its `.optional()` / `.default()` WRAPPER and
+ * comes from another zod release than the engine's. Measured before: the adoption judged only
+ * the wrapper's `innerType`, so `'forbidden'` — refused by the column's own `safeParse` — was
+ * STORED (create and edit). Now a supplied value is judged by the whole column; the engine's own
+ * copy is the control row (composed as it is, refused before too). `zod-copy-older` (4.1.13) and
+ * `zod-copy-newer` (4.6.7) are real second copies (aliased devDependencies), not mocks.
+ */
+
+const MESSAGE = 'forbidden value'
+const notForbidden = (value: string | undefined) => value !== 'forbidden'
+
+// The copies' builders differ only in their TYPES (EC-639 owns those); the runtime is the subject here.
+type Vendor = typeof z
+const COPIES = [
+  ['own', 'the engine’s own copy (the control)', z],
+  ['older', 'an OLDER zod copy (4.1.13)', olderZod as unknown as Vendor],
+  ['newer', 'a NEWER zod copy (4.6.7)', newerZod as unknown as Vendor],
+] as const
+
+const SHAPES = [
+  // The defect: the refinement is the WRAPPER's own check.
+  ['OptionalRefine', 'optional().refine()', (v: Vendor) => v.string().optional().refine(notForbidden, MESSAGE)],
+  ['DefaultRefine', 'default().refine()', (v: Vendor) => v.string().default('safe').refine(notForbidden, MESSAGE)],
+  // The neighbours: the refinement sits on the inner type (judged before this change too).
+  ['RefineOptional', 'refine().optional()', (v: Vendor) => v.string().refine(notForbidden, MESSAGE).optional()],
+  ['RefineDefault', 'refine().default()', (v: Vendor) => v.string().refine(notForbidden, MESSAGE).default('safe')],
+] as const
+
+const CASES = COPIES.flatMap(([copy, copyLabel, vendor]) =>
+  SHAPES.map(([shape, shapeLabel, build]) => {
+    const kind = defineRecordKind({
+      kind: `${copy}${shape}`,
+      module: `${copy}${shape}Notes`,
+      fields: { code: build(vendor) as unknown as RecordColumnSchema },
+    })
+    return [`${copyLabel}, \`z.string().${shapeLabel}\``, { kind, defaulted: shape.includes('Default') }] as const
+  }),
+)
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+  ...Object.fromEntries(CASES.map(([, { kind }]) => [`./${kind.module}.ts`, async () => defineRecordFunctions(kind)])),
+}
+
+const STAMP = '2026-10-28T00:00:00.000Z'
+
+async function editorBackend() {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: 'editor', role: 'editor', createdAt: STAMP, updatedAt: STAMP })
+  })
+  return { t, editor: t.withIdentity({ subject: 'editor', issuer: 'https://convex.test' }) }
+}
+
+describe.each(CASES)('EC-682 — Convex record save, %s', (_label, { kind, defaulted }: { kind: AnyRecordKind; defaulted: boolean }) => {
+  const save = makeFunctionReference<'mutation'>(`${kind.module}:save`)
+  const get = makeFunctionReference<'query'>(`${kind.module}:get`)
+  const write = (id: string, columns: Record<string, unknown> = {}) => ({ [kind.idKey]: id, ...columns, createdAt: STAMP, updatedAt: STAMP })
+
+  it('refuses `forbidden` on create with the column’s own message, in the transaction — nothing stored', async () => {
+    const { t, editor } = await editorBackend()
+    await expect(editor.mutation(save, write('created', { code: 'forbidden' }))).rejects.toThrow(/code: forbidden value/)
+    expect(await t.run(async (ctx) => ctx.db.query('records').collect())).toEqual([])
+  })
+
+  it('saves `safe`, refuses an edit to `forbidden`, keeps the stored value', async () => {
+    const { editor } = await editorBackend()
+    expect(await editor.mutation(save, write('edited', { code: 'safe' }))).toMatchObject({ code: 'safe' })
+    await expect(editor.mutation(save, write('edited', { code: 'forbidden' }))).rejects.toThrow(/code: forbidden value/)
+    expect(await editor.query(get, { [kind.idKey]: 'edited' })).toMatchObject({ code: 'safe' })
+  })
+
+  it('an absent key is the wrapper’s: the optional stays absent, the default is the column’s own (`safe`)', async () => {
+    const { editor } = await editorBackend()
+    const created = (await editor.mutation(save, write('absent'))) as Record<string, unknown>
+    if (defaulted) expect(created.code).toBe('safe')
+    else expect('code' in created).toBe(false)
+  })
+})

package/convex/schema.ts

@@ -302,7 +302,7 @@ export default defineSchema({
     updatedAt: v.string(),
   })
     .index('by_asset', ['assetId'])
-    // EC-671: an ingest claim refuses a storage id an asset row references (`claimIngestUpload`).
+    // EC-671: an ingest claim refuses a storage id an asset row references (`claimIngestUploads`, EC-695).
     .index('by_storage', ['storageKey'])
     .index('by_thumb_storage', ['thumb.storageKey']),
 

package/dist/addon.d.ts

@@ -14,9 +14,10 @@
  * ## 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
+ * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail, the issues badge
+ * and tray in the header (EC-690: findings contributed with {@link useNavIssues}, or
+ * always-on through a view's `useIssues`; a finding may carry a {@link NoticeLocation} the
+ * tray's "Go to" opens) 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
@@ -55,6 +56,7 @@ 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';
+export type { NoticeLocation } from './components/notifications/notice-model.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';

package/dist/addon.js

@@ -14,9 +14,10 @@
  * ## 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
+ * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail, the issues badge
+ * and tray in the header (EC-690: findings contributed with {@link useNavIssues}, or
+ * always-on through a view's `useIssues`; a finding may carry a {@link NoticeLocation} the
+ * tray's "Go to" opens) 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

package/dist/addon.js.map

@@ -1 +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"]}
+{"version":3,"file":"addon.js","sourceRoot":"","sources":["../src/addon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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;AAI/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, the issues badge\n * and tray in the header (EC-690: findings contributed with {@link useNavIssues}, or\n * always-on through a view's `useIssues`; a finding may carry a {@link NoticeLocation} the\n * tray's \"Go to\" opens) 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'\nexport type { NoticeLocation } from './components/notifications/notice-model'\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"]}

package/dist/components/app-views/default-modules.d.ts

@@ -108,8 +108,15 @@ export interface CustomViewConfig {
     availabilitySection?: SectionId;
     /** OPTIONAL, default-open nav-permission predicate (EC-240 / AD-18). See {@link BuiltinViewConfig.visible}. */
     visible?: NavPermission;
-    /** Always-on rail-foot findings for this view (EC-616, see `NavIssuesHook`). */
+    /** Always-on findings for the shell's issues tray (EC-616, see `NavIssuesHook`). */
     useIssues?: NavIssuesHook;
+    /**
+     * EC-690 — the record kind this view lists, when it is a custom surface over one (the forms
+     * inbox lists `submission`s): a finding located at a record of that kind
+     * (`{ kind: 'record', recordKind, id? }`) then opens HERE, and reaches whoever can open this
+     * view. A record rail (`nav.rail(kind)`) declares it itself.
+     */
+    recordKind?: string;
 }
 /**
  * Derive a stable, deterministic id from the CMS focus (overridable via `config.id`).
@@ -184,7 +191,7 @@ export interface RailViewConfig extends BuiltinViewConfig {
     /** Narrow the default capabilities (create, edit, remove, bulk delete). */
     capabilities?: Partial<CollectionViewCapabilities>;
     availabilitySection?: SectionId;
-    /** Always-on rail-foot findings for this rail (EC-616, see `NavIssuesHook`). */
+    /** Always-on findings for the shell's issues tray (EC-616, see `NavIssuesHook`). */
     useIssues?: NavIssuesHook;
     /** Copy for the loading / failure states (default: generic catalog copy naming the label). */
     messages?: {
@@ -272,7 +279,7 @@ export interface SidebarIdKeyspace {
      * else passes through untouched, including the merely-ambiguous EC-477 case.
      */
     views: AppViewModule[];
-    /** What was found — visible at the rail foot, never silent. */
+    /** What was found — visible in the issues tray, never silent. */
     issues: CustomizationIssue[];
 }
 /**

package/dist/components/app-views/default-modules.js

@@ -239,6 +239,9 @@ export function railView(kind, config = {}) {
         icon: config.icon ?? Database,
         ...(config.availabilitySection ? { availabilitySection: config.availabilitySection } : {}),
         ...(config.useIssues ? { useIssues: config.useIssues } : {}),
+        // EC-690: a finding located at a record (`{ kind: 'record', recordKind }`) resolves to
+        // the rail listing that kind — whatever view id the consumer gave it.
+        recordKind: kind.kind,
         parsePath: recordDeepLink(kind.idKey),
         render: (ctx) => ctx.search.state && ctx.search.state !== 'working' ? (_jsx(SectionStateView, { state: ctx.search.state, title: label() })) : (_jsx(RecordRailModule, { kind: kind, projectId: ctx.projectId, recordId: ctx.deepLink[kind.idKey] ?? null, schema: schema, paths: paths, capabilities: capabilities, label: label(), ...(config.messages ? { messages: config.messages } : {}) })),
     };
@@ -371,6 +374,7 @@ export function customView(config) {
         ...(config.parsePath ? { parsePath: config.parsePath } : {}),
         ...(config.availabilitySection ? { availabilitySection: config.availabilitySection } : {}),
         ...(config.useIssues ? { useIssues: config.useIssues } : {}),
+        ...(config.recordKind ? { recordKind: config.recordKind } : {}),
     };
 }
 /**
@@ -400,7 +404,7 @@ const SIDEBAR_POINT = 'sidebar';
 /**
  * The catalog keys for the two keyspace findings (EC-478). This module stays pure —
  * it names a key and its identifier values; `lib/persona/labels.ts` resolves them at
- * the render site, so the rail foot localizes as one list.
+ * the render site, so the issues tray localizes as one list.
  */
 const KEYSPACE_KEYS = {
     builtinCollision: 'customization.issue.derivedIdBuiltinCollision',