@elytracms/studio 0.0.98 → 0.0.99

package/dist/lib/notices/toast-store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * EC-690 — the TRANSIENT channel of the studio's one notification-and-issue surface: an
+ * action's outcome (a publish that failed, a copy that was made). Persistent findings (a
+ * duplicate redirect, a config problem) live in the shell's findings registry instead
+ * (`components/nav-issues-registry.tsx`); both render in the one issues tray.
+ *
+ * The rules, owner-ratified 2026-10-28 ("As recommended", ruling (d)):
+ * - a SUCCESS expires on its own after {@link NOTICE_PEEK_MS};
+ * - an ERROR stays until it is dismissed — it is never lost to a timer;
+ * - every notice PEEKS for {@link NOTICE_PEEK_MS} when it is raised (bottom-right of the
+ *   content area), and lives on in the tray for as long as it lives at all.
+ *
+ * A KEYED notice is an outcome its owner tracks (a failed save its store holds as
+ * `persistError` / `lastError`): the owner raises it while the error is set and retracts it
+ * when the error clears, and dismissing it in the tray calls the owner's `onDismiss` — so the
+ * inline banner and the tray are two views of ONE state, never two states.
+ *
+ * Pure and clock-injected ({@link createToastStore}): the module's default store binds the
+ * real clock, tests bind their own (AGENTS §4 determinism — no `Date.now()`/`setTimeout` in
+ * the logic under test).
+ */
+export type ToastVariant = 'error' | 'success';
+export interface ToastItem {
+    id: number;
+    message: string;
+    variant: ToastVariant;
+    /** When the notice leaves on its own (epoch ms); `null` = it stays until dismissed (every error). */
+    expiresAt: number | null;
+    /** Whether it is still in its first {@link NOTICE_PEEK_MS} (shown in the content area's corner). */
+    peeking: boolean;
+    /** The owner's key, for a notice its owner raises and retracts (absent for a plain `toast.*`). */
+    key?: string;
+}
+/** How long a notice peeks, and how long a success lives (EC-268's original 5 s). */
+export declare const NOTICE_PEEK_MS = 5000;
+/** The clock the store reads — injected so the logic is deterministic under test. */
+export interface ToastClock {
+    now(): number;
+    /** Run `run` after `ms`; returns a cancel function. */
+    schedule(run: () => void, ms: number): () => void;
+}
+export interface KeyedToastInput {
+    message: string;
+    variant: ToastVariant;
+    /** Called when the reader dismisses it (e.g. `clearPersistError`) — not on {@link ToastStore.retract}. */
+    onDismiss?: () => void;
+}
+export interface ToastStore {
+    push(message: string, variant: ToastVariant): number;
+    /** Raise (or keep) the owner's notice under `key`. The same message again is a no-op; a new one replaces it. */
+    raise(key: string, input: KeyedToastInput): number;
+    /** The owner's state cleared: remove its notice WITHOUT calling `onDismiss`. */
+    retract(key: string): void;
+    /** The reader dismissed it: remove it and tell its owner. */
+    dismiss(id: number): void;
+    getSnapshot(): ToastItem[];
+    subscribe(listener: (items: ToastItem[]) => void): () => void;
+}
+export declare function createToastStore(clock: ToastClock): ToastStore;
+/** The studio's one transient channel (`toast.*` writes it, the issues tray reads it). */
+export declare const studioToasts: ToastStore;

package/dist/lib/notices/toast-store.js

@@ -0,0 +1,116 @@
+/**
+ * EC-690 — the TRANSIENT channel of the studio's one notification-and-issue surface: an
+ * action's outcome (a publish that failed, a copy that was made). Persistent findings (a
+ * duplicate redirect, a config problem) live in the shell's findings registry instead
+ * (`components/nav-issues-registry.tsx`); both render in the one issues tray.
+ *
+ * The rules, owner-ratified 2026-10-28 ("As recommended", ruling (d)):
+ * - a SUCCESS expires on its own after {@link NOTICE_PEEK_MS};
+ * - an ERROR stays until it is dismissed — it is never lost to a timer;
+ * - every notice PEEKS for {@link NOTICE_PEEK_MS} when it is raised (bottom-right of the
+ *   content area), and lives on in the tray for as long as it lives at all.
+ *
+ * A KEYED notice is an outcome its owner tracks (a failed save its store holds as
+ * `persistError` / `lastError`): the owner raises it while the error is set and retracts it
+ * when the error clears, and dismissing it in the tray calls the owner's `onDismiss` — so the
+ * inline banner and the tray are two views of ONE state, never two states.
+ *
+ * Pure and clock-injected ({@link createToastStore}): the module's default store binds the
+ * real clock, tests bind their own (AGENTS §4 determinism — no `Date.now()`/`setTimeout` in
+ * the logic under test).
+ */
+/** How long a notice peeks, and how long a success lives (EC-268's original 5 s). */
+export const NOTICE_PEEK_MS = 5000;
+export function createToastStore(clock) {
+    let items = [];
+    let seq = 0;
+    const listeners = new Set();
+    const cancels = new Map();
+    const onDismiss = new Map();
+    const emit = () => {
+        for (const listener of [...listeners])
+            listener(items);
+    };
+    const drop = (id) => {
+        const item = items.find((candidate) => candidate.id === id);
+        if (!item)
+            return undefined;
+        items = items.filter((candidate) => candidate.id !== id);
+        cancels.get(id)?.();
+        cancels.delete(id);
+        return item;
+    };
+    const add = (message, variant, key) => {
+        const id = ++seq;
+        const raisedAt = clock.now();
+        const expiresAt = variant === 'success' ? raisedAt + NOTICE_PEEK_MS : null;
+        items = [...items, { id, message, variant, expiresAt, peeking: true, ...(key !== undefined ? { key } : {}) }];
+        cancels.set(id, clock.schedule(() => {
+            cancels.delete(id);
+            if (variant === 'success') {
+                onDismiss.delete(id);
+                items = items.filter((candidate) => candidate.id !== id);
+            }
+            else {
+                items = items.map((candidate) => (candidate.id === id ? { ...candidate, peeking: false } : candidate));
+            }
+            emit();
+        }, NOTICE_PEEK_MS));
+        emit();
+        return id;
+    };
+    return {
+        push: (message, variant) => add(message, variant),
+        raise(key, input) {
+            const current = items.find((item) => item.key === key);
+            if (current && current.message === input.message && current.variant === input.variant) {
+                if (input.onDismiss)
+                    onDismiss.set(current.id, input.onDismiss);
+                return current.id;
+            }
+            if (current) {
+                drop(current.id);
+                onDismiss.delete(current.id);
+            }
+            const id = add(input.message, input.variant, key);
+            if (input.onDismiss)
+                onDismiss.set(id, input.onDismiss);
+            return id;
+        },
+        retract(key) {
+            const current = items.find((item) => item.key === key);
+            if (!current)
+                return;
+            drop(current.id);
+            onDismiss.delete(current.id);
+            emit();
+        },
+        dismiss(id) {
+            const item = drop(id);
+            if (!item)
+                return;
+            const owner = onDismiss.get(id);
+            onDismiss.delete(id);
+            emit();
+            owner?.();
+        },
+        getSnapshot: () => items,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+/** The real clock — the one place the studio's notices read wall time. */
+const realClock = {
+    now: () => Date.now(),
+    schedule: (run, ms) => {
+        const handle = setTimeout(run, ms);
+        return () => clearTimeout(handle);
+    },
+};
+/** The studio's one transient channel (`toast.*` writes it, the issues tray reads it). */
+export const studioToasts = createToastStore(realClock);
+//# sourceMappingURL=toast-store.js.map

package/dist/lib/notices/toast-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toast-store.js","sourceRoot":"","sources":["../../../src/lib/notices/toast-store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * EC-690 — the TRANSIENT channel of the studio's one notification-and-issue surface: an\n * action's outcome (a publish that failed, a copy that was made). Persistent findings (a\n * duplicate redirect, a config problem) live in the shell's findings registry instead\n * (`components/nav-issues-registry.tsx`); both render in the one issues tray.\n *\n * The rules, owner-ratified 2026-10-28 (\"As recommended\", ruling (d)):\n * - a SUCCESS expires on its own after {@link NOTICE_PEEK_MS};\n * - an ERROR stays until it is dismissed — it is never lost to a timer;\n * - every notice PEEKS for {@link NOTICE_PEEK_MS} when it is raised (bottom-right of the\n *   content area), and lives on in the tray for as long as it lives at all.\n *\n * A KEYED notice is an outcome its owner tracks (a failed save its store holds as\n * `persistError` / `lastError`): the owner raises it while the error is set and retracts it\n * when the error clears, and dismissing it in the tray calls the owner's `onDismiss` — so the\n * inline banner and the tray are two views of ONE state, never two states.\n *\n * Pure and clock-injected ({@link createToastStore}): the module's default store binds the\n * real clock, tests bind their own (AGENTS §4 determinism — no `Date.now()`/`setTimeout` in\n * the logic under test).\n */\n\nexport type ToastVariant = 'error' | 'success'\n\nexport interface ToastItem {\n  id: number\n  message: string\n  variant: ToastVariant\n  /** When the notice leaves on its own (epoch ms); `null` = it stays until dismissed (every error). */\n  expiresAt: number | null\n  /** Whether it is still in its first {@link NOTICE_PEEK_MS} (shown in the content area's corner). */\n  peeking: boolean\n  /** The owner's key, for a notice its owner raises and retracts (absent for a plain `toast.*`). */\n  key?: string\n}\n\n/** How long a notice peeks, and how long a success lives (EC-268's original 5 s). */\nexport const NOTICE_PEEK_MS = 5000\n\n/** The clock the store reads — injected so the logic is deterministic under test. */\nexport interface ToastClock {\n  now(): number\n  /** Run `run` after `ms`; returns a cancel function. */\n  schedule(run: () => void, ms: number): () => void\n}\n\nexport interface KeyedToastInput {\n  message: string\n  variant: ToastVariant\n  /** Called when the reader dismisses it (e.g. `clearPersistError`) — not on {@link ToastStore.retract}. */\n  onDismiss?: () => void\n}\n\nexport interface ToastStore {\n  push(message: string, variant: ToastVariant): number\n  /** Raise (or keep) the owner's notice under `key`. The same message again is a no-op; a new one replaces it. */\n  raise(key: string, input: KeyedToastInput): number\n  /** The owner's state cleared: remove its notice WITHOUT calling `onDismiss`. */\n  retract(key: string): void\n  /** The reader dismissed it: remove it and tell its owner. */\n  dismiss(id: number): void\n  getSnapshot(): ToastItem[]\n  subscribe(listener: (items: ToastItem[]) => void): () => void\n}\n\nexport function createToastStore(clock: ToastClock): ToastStore {\n  let items: ToastItem[] = []\n  let seq = 0\n  const listeners = new Set<(items: ToastItem[]) => void>()\n  const cancels = new Map<number, () => void>()\n  const onDismiss = new Map<number, () => void>()\n\n  const emit = (): void => {\n    for (const listener of [...listeners]) listener(items)\n  }\n\n  const drop = (id: number): ToastItem | undefined => {\n    const item = items.find((candidate) => candidate.id === id)\n    if (!item) return undefined\n    items = items.filter((candidate) => candidate.id !== id)\n    cancels.get(id)?.()\n    cancels.delete(id)\n    return item\n  }\n\n  const add = (message: string, variant: ToastVariant, key?: string): number => {\n    const id = ++seq\n    const raisedAt = clock.now()\n    const expiresAt = variant === 'success' ? raisedAt + NOTICE_PEEK_MS : null\n    items = [...items, { id, message, variant, expiresAt, peeking: true, ...(key !== undefined ? { key } : {}) }]\n    cancels.set(\n      id,\n      clock.schedule(() => {\n        cancels.delete(id)\n        if (variant === 'success') {\n          onDismiss.delete(id)\n          items = items.filter((candidate) => candidate.id !== id)\n        } else {\n          items = items.map((candidate) => (candidate.id === id ? { ...candidate, peeking: false } : candidate))\n        }\n        emit()\n      }, NOTICE_PEEK_MS),\n    )\n    emit()\n    return id\n  }\n\n  return {\n    push: (message, variant) => add(message, variant),\n    raise(key, input) {\n      const current = items.find((item) => item.key === key)\n      if (current && current.message === input.message && current.variant === input.variant) {\n        if (input.onDismiss) onDismiss.set(current.id, input.onDismiss)\n        return current.id\n      }\n      if (current) {\n        drop(current.id)\n        onDismiss.delete(current.id)\n      }\n      const id = add(input.message, input.variant, key)\n      if (input.onDismiss) onDismiss.set(id, input.onDismiss)\n      return id\n    },\n    retract(key) {\n      const current = items.find((item) => item.key === key)\n      if (!current) return\n      drop(current.id)\n      onDismiss.delete(current.id)\n      emit()\n    },\n    dismiss(id) {\n      const item = drop(id)\n      if (!item) return\n      const owner = onDismiss.get(id)\n      onDismiss.delete(id)\n      emit()\n      owner?.()\n    },\n    getSnapshot: () => items,\n    subscribe(listener) {\n      listeners.add(listener)\n      return () => {\n        listeners.delete(listener)\n      }\n    },\n  }\n}\n\n/** The real clock — the one place the studio's notices read wall time. */\nconst realClock: ToastClock = {\n  now: () => Date.now(),\n  schedule: (run, ms) => {\n    const handle = setTimeout(run, ms)\n    return () => clearTimeout(handle)\n  },\n}\n\n/** The studio's one transient channel (`toast.*` writes it, the issues tray reads it). */\nexport const studioToasts: ToastStore = createToastStore(realClock)\n"]}

package/dist/lib/operations/cms-persistence.d.ts

@@ -44,7 +44,12 @@ import type { OperationError, OperationsClient } from './operations-package.js';
  *   the base it was authored at. `revisionOfView(view, path)` is the revision the content
  *   at `path` was authored against: the earliest of the floor and of the shown writes that
  *   OVERLAP `path` — at it, at an ancestor, or at a descendant, whose content the value at
- *   `path` contains (EC-681, Codex F23); a sibling's write does not lower it.
+ *   `path` contains (EC-681, Codex F23); a sibling's write does not lower it. Positions
+ *   are compared in their STRUCTURAL form, as the store compares them (EC-693, Codex F28):
+ *   a node path carries its component ancestry — each shown write's as the merge applied
+ *   it in that view, the asked path's expanded against the view — so a parent node's token
+ *   sees a pending write of its child's prop, which a submitted `nodePropPath` names
+ *   without the parent.
  *   `revisionOfView(view)` — a whole-document writer — the EARLIEST of all. The record is
  *   immutable, so it outlives the pending write: an edit started on a view that showed a
  *   snapshot keeps the snapshot's revision after the snapshot is refused or fails
@@ -59,7 +64,8 @@ import type { OperationError, OperationsClient } from './operations-package.js';
  * - **The own-write ledger.** A base may be LIFTED, at send time, across revisions this
  *   persister wrote — and only those: across a run of consecutive own revisions right
  *   after it (nothing foreign happened in between), or to an own write's revision when
- *   the patch only touches positions that write covered and the write was sent at or
+ *   the patch only touches positions that write covered (both read where they land in the
+ *   server row, node ancestry included — EC-693) and the write was sent at or
  *   below the patch's base (the store refused every foreign change of those positions in
  *   between, or the write would not have applied) — or, EC-681, across a revision someone
  *   else wrote that the patch log shows touched none of the patch's positions (the store
@@ -112,7 +118,13 @@ export type CommitOutcome = {
     readonly status: 'refused';
     readonly conflicts: readonly DocumentConflict[];
 }
-/** A transport / authorization failure, or a write that named no authoring revision (also reported through `onError`). */
+/**
+ * A transport / authorization failure, or a write that named no authoring revision (also
+ * reported through `onError`). A write the backend did not judge is KEPT (EC-674): it
+ * stays shown and queued, and the next commit or forced flush re-sends it — its commit,
+ * and every commit queued behind it, settles `failed` with that error when the drain
+ * stops on it (EC-686), never left waiting.
+ */
  | {
     readonly status: 'failed';
     readonly error: OperationError;
@@ -170,8 +182,16 @@ export interface CmsPersister {
      * conflict, never overwritten. `revision` `undefined`: the snapshot was authored on a
      * provisional view (our own pending create; insert-if-absent when untracked). Sent in
      * its place among the session's queued patches.
+     *
+     * EC-686 (the owner's ruling, per-position): when the store refuses it, it is decomposed
+     * into what the author changed against `authoredOn` — the document the snapshot was made
+     * from — and each position is re-sent: it lands, or becomes that field's ordinary
+     * conflict. Never a whole-document keep-mine. Without `authoredOn` nothing can be judged
+     * per position: the refusal adopts the current row and is reported, as before — never a
+     * guess (the session's view at that moment may hold changes the snapshot never saw, which
+     * a diff against it would re-send as the author's).
      */
-    replace(document: CmsDocument, revision: number | undefined): void;
+    replace(document: CmsDocument, revision: number | undefined, authoredOn?: CmsDocument): void;
     deleteDocument(ref: DocumentRef): void;
     unpublishDocument(ref: DocumentRef): void;
     /**