@volter/editor-core 0.5.57

package/src/authoring/consumer-actions.ts

@@ -0,0 +1,520 @@
+import type {
+  AssetDropContext,
+  AuthoringAdapter,
+  ComponentInstanceApplyResult,
+  SpatialHandlesProvider,
+  StructuralClipboardOutcome,
+  StructuralIdsWrite,
+  StructuralIdWrite,
+  StructuralWriteOutcome,
+  Transform,
+  TransformChannel,
+  WriteAck,
+} from '@volter/editor-project/adapter';
+import {
+  recordAuthoringConsumerUse,
+  recordAuthoringWriteConsumerUse,
+} from '../coverage/authoring-seam-evidence';
+
+export function setAuthoringSelection(
+  adapter: AuthoringAdapter,
+  nodeIds: readonly string[],
+  options?: { intent?: 'semantic' | 'exact' },
+): boolean {
+  const provider = adapter.selection;
+  if (!provider) return false;
+  recordAuthoringConsumerUse({
+    adapter,
+    seam: 'editor.selection.set',
+    stage: 'effect',
+    detail: `the editor selected ${nodeIds.length} authoring subject(s)`,
+    run: () => provider.set([...nodeIds], options),
+  });
+  return true;
+}
+
+export function beginAuthoringTransformEdit(adapter: AuthoringAdapter, nodeId: string): boolean {
+  const provider = adapter.transforms;
+  if (!provider) return false;
+  recordAuthoringConsumerUse({
+    adapter,
+    seam: 'editor.transforms.beginEdit',
+    stage: 'effect',
+    detail: `the editor began a transform gesture on ${nodeId}`,
+    run: () => provider.beginEdit(nodeId),
+  });
+  return true;
+}
+
+export function applyAuthoringTransform(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  transform: Transform,
+): boolean {
+  const provider = adapter.transforms;
+  if (!provider) return false;
+  recordAuthoringConsumerUse({
+    adapter,
+    seam: 'editor.transforms.apply',
+    stage: 'effect',
+    detail: `the editor applied a transform to ${nodeId}`,
+    run: () => provider.apply(nodeId, transform),
+  });
+  return true;
+}
+
+export function endAuthoringTransformEdit(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): StructuralWriteOutcome {
+  const provider = adapter.transforms;
+  if (!provider) return;
+  return recordAuthoringWriteConsumerUse({
+    adapter,
+    seam: 'editor.transforms.endEdit',
+    detail: `the editor completed a transform gesture on ${nodeId}`,
+    run: () => provider.endEdit(nodeId),
+  });
+}
+
+export function removeAuthoringTransform(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  channel: TransformChannel,
+): StructuralWriteOutcome {
+  const remove = adapter.transforms?.remove;
+  if (!remove) return;
+  return recordAuthoringWriteConsumerUse({
+    adapter,
+    seam: 'editor.transforms.remove',
+    detail: `the editor removed transform ${channel} from ${nodeId}`,
+    run: () => remove(nodeId, channel),
+  });
+}
+
+/** The explicit Play→source gesture. Ordinary transform edits never call this;
+ * the Inspector action is the sole shell consumer. */
+export function commitAuthoringTransformSource(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): StructuralWriteOutcome {
+  const provider = adapter.transforms?.sourceCommit;
+  if (!provider) return;
+  return recordAuthoringWriteConsumerUse({
+    adapter,
+    seam: 'editor.transforms.sourceCommit',
+    detail: `the user committed the live transform of ${nodeId} to source`,
+    run: () => provider.commit(nodeId),
+  });
+}
+
+/** Save one adapter-owned document through its native persistence provider.
+ * A clean save may still let the provider flush bookkeeping, but it cannot
+ * manufacture evidence that bytes round-tripped. Composite adapters call this
+ * again at the child boundary, so one shell action records both the composite
+ * and the exact dirty root that actually saved. */
+export async function saveAuthoringDocument(
+  adapter: AuthoringAdapter,
+  detail = 'the editor saved the active authoring document',
+): Promise<void> {
+  const provider = adapter.persistence;
+  if (!provider) return;
+  if (!provider.isDirty()) {
+    await provider.save();
+    return;
+  }
+  await recordAuthoringConsumerUse({
+    adapter,
+    seam: 'editor.persistence.save',
+    stage: 'round-trip',
+    detail: `${detail} to ${provider.destination}`,
+    run: () => provider.save(),
+  });
+}
+
+/** Write one Inspector field through the provider that owns it and retain the
+ * provider's own acknowledgement. Every Inspector-shaped surface uses this
+ * action so coverage and write truth do not depend on which panel initiated
+ * the same edit. */
+export function setAuthoringInspectorField(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  path: string,
+  value: unknown,
+): StructuralWriteOutcome {
+  const provider = adapter.inspector;
+  if (!provider) return;
+  return recordAuthoringWriteConsumerUse({
+    adapter,
+    seam: 'editor.inspector.set',
+    detail: `the editor wrote ${path} on ${nodeId}`,
+    run: () => provider.set(nodeId, path, value),
+  });
+}
+
+export function removeAuthoringInspectorField(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  path: string,
+): StructuralWriteOutcome {
+  const remove = adapter.inspector?.remove;
+  if (!remove) return;
+  return recordAuthoringWriteConsumerUse({
+    adapter,
+    seam: 'editor.inspector.remove',
+    detail: `the editor removed ${path} from ${nodeId}`,
+    run: () => remove(nodeId, path),
+  });
+}
+
+/** Route one accepted asset drop through its real adapter and retain exactly
+ * the strength of the provider's own acknowledgement. Composite adapters use
+ * this again at their child boundary, so per-root coverage follows ownership
+ * instead of stopping at the shell router. */
+export function dropAuthoringAsset(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  assetPath: string,
+  context?: AssetDropContext,
+): StructuralWriteOutcome {
+  const provider = adapter.assetDrop;
+  if (!provider) return;
+  return recordAuthoringWriteConsumerUse({
+    adapter,
+    seam: 'editor.assetDrop.drop',
+    detail: `the editor dropped ${assetPath} on ${nodeId || 'the root'}`,
+    run: () =>
+      context === undefined
+        ? provider.drop(nodeId, assetPath)
+        : provider.drop(nodeId, assetPath, context),
+  });
+}
+
+export function openAuthoringComponent(adapter: AuthoringAdapter, nodeId: string): void {
+  const provider = adapter.instances;
+  if (!provider?.openComponent) return;
+  recordAuthoringConsumerUse({
+    adapter,
+    seam: 'editor.instances.openComponent',
+    stage: 'effect',
+    detail: `the Inspector opened the component owning ${nodeId}`,
+    run: () => provider.openComponent?.(nodeId),
+  });
+}
+
+export function revertAuthoringInstance(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  paths: readonly string[],
+): Promise<WriteAck | undefined> {
+  const provider = adapter.instances;
+  if (!provider) return Promise.resolve(undefined);
+  return Promise.resolve(
+    recordAuthoringWriteConsumerUse({
+      adapter,
+      seam: 'editor.instances.revert',
+      detail: `the Inspector reverted ${paths.length} override(s) on ${nodeId}`,
+      run: () => provider.revert(nodeId, paths),
+    }),
+  ).then((ack) => ack ?? undefined);
+}
+
+export async function applyAuthoringInstanceToComponent(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  path: string,
+): Promise<ComponentInstanceApplyResult> {
+  const provider = adapter.instances;
+  if (!provider) return { changed: false, message: 'This subject has no component instance.' };
+  const result = await provider.applyToComponent(nodeId, path);
+  await recordAuthoringWriteConsumerUse({
+    adapter,
+    seam: 'editor.instances.applyToComponent',
+    detail: `the Inspector applied ${path} from ${nodeId} to its component`,
+    run: () => result.write,
+  });
+  return result;
+}
+
+function structureWrite(
+  adapter: AuthoringAdapter,
+  verb: string,
+  detail: string,
+  run: () => StructuralWriteOutcome,
+): StructuralWriteOutcome {
+  return recordAuthoringWriteConsumerUse({
+    adapter,
+    seam: `editor.structure.${verb}`,
+    detail,
+    run,
+  });
+}
+
+function structureIdWrite<Id extends string | null>(
+  adapter: AuthoringAdapter,
+  verb: string,
+  detail: string,
+  run: () => StructuralIdWrite<Id>,
+): StructuralIdWrite<Id> {
+  const result = recordAuthoringConsumerUse({
+    adapter,
+    seam: `editor.structure.${verb}`,
+    stage: 'effect',
+    detail,
+    run,
+  });
+  return {
+    ...result,
+    ack: structureWrite(adapter, verb, detail, () => result.ack),
+  };
+}
+
+export function createAuthoringNode(
+  adapter: AuthoringAdapter,
+  kind: string,
+  parentId?: string,
+): StructuralIdWrite {
+  const provider = adapter.structure;
+  if (!provider) return { id: '', ack: undefined };
+  return structureIdWrite(
+    adapter,
+    'create',
+    `the editor created a ${kind} under ${parentId ?? 'the document root'}`,
+    () => provider.create(kind, parentId),
+  );
+}
+
+export function removeAuthoringNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): StructuralWriteOutcome {
+  const provider = adapter.structure;
+  if (!provider) return;
+  return structureWrite(adapter, 'remove', `the editor removed ${nodeId}`, () =>
+    provider.remove(nodeId),
+  );
+}
+
+export function removeManyAuthoringNodes(
+  adapter: AuthoringAdapter,
+  nodeIds: readonly string[],
+): StructuralWriteOutcome {
+  const provider = adapter.structure;
+  if (!provider?.removeMany) return;
+  return structureWrite(
+    adapter,
+    'removeMany',
+    `the editor removed ${nodeIds.length} selected node(s) as one operation`,
+    () => provider.removeMany?.(nodeIds),
+  );
+}
+
+export function duplicateAuthoringNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): StructuralIdWrite {
+  const provider = adapter.structure;
+  if (!provider) return { id: nodeId, ack: undefined };
+  return structureIdWrite(adapter, 'duplicate', `the editor duplicated ${nodeId}`, () =>
+    provider.duplicate(nodeId),
+  );
+}
+
+export function reparentAuthoringNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  parentId: string | null,
+): StructuralWriteOutcome {
+  const provider = adapter.structure;
+  if (!provider) return;
+  return structureWrite(
+    adapter,
+    'reparent',
+    `the editor reparented ${nodeId} under ${parentId ?? 'the document root'}`,
+    () => provider.reparent(nodeId, parentId),
+  );
+}
+
+export function reorderAuthoringNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  beforeSiblingId: string | null,
+): StructuralWriteOutcome {
+  const provider = adapter.structure;
+  if (!provider?.reorder) return;
+  return structureWrite(
+    adapter,
+    'reorder',
+    `the editor reordered ${nodeId} before ${beforeSiblingId ?? 'the end'}`,
+    () => provider.reorder?.(nodeId, beforeSiblingId),
+  );
+}
+
+export function wrapAuthoringNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  wrapperTag?: string,
+): StructuralWriteOutcome {
+  const provider = adapter.structure;
+  if (!provider?.wrap) return;
+  return structureWrite(adapter, 'wrap', `the editor wrapped ${nodeId}`, () =>
+    provider.wrap?.(nodeId, wrapperTag),
+  );
+}
+
+export function unwrapAuthoringNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): StructuralWriteOutcome {
+  const provider = adapter.structure;
+  if (!provider?.unwrap) return;
+  return structureWrite(adapter, 'unwrap', `the editor unwrapped ${nodeId}`, () =>
+    provider.unwrap?.(nodeId),
+  );
+}
+
+export function groupAuthoringNodes(
+  adapter: AuthoringAdapter,
+  nodeIds: readonly string[],
+): StructuralIdWrite<string | null> {
+  const provider = adapter.structure;
+  if (!provider?.group) return { id: null, ack: undefined };
+  return structureIdWrite(
+    adapter,
+    'group',
+    `the editor grouped ${nodeIds.length} selected node(s)`,
+    () => provider.group?.(nodeIds) ?? { id: null, ack: undefined },
+  );
+}
+
+export function ungroupAuthoringNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): StructuralIdsWrite {
+  const provider = adapter.structure;
+  if (!provider?.ungroup) return { ids: [], ack: undefined };
+  const result = recordAuthoringConsumerUse({
+    adapter,
+    seam: 'editor.structure.ungroup',
+    stage: 'effect',
+    detail: `the editor ungrouped ${nodeId}`,
+    run: () => provider.ungroup?.(nodeId) ?? { ids: [], ack: undefined },
+  });
+  return {
+    ...result,
+    ack: structureWrite(adapter, 'ungroup', `the editor ungrouped ${nodeId}`, () => result.ack),
+  };
+}
+
+export async function copyAuthoringNodes(
+  adapter: AuthoringAdapter,
+  nodeIds: readonly string[],
+): Promise<boolean> {
+  const provider = adapter.structure;
+  if (!provider?.copy) return false;
+  return await recordAuthoringConsumerUse({
+    adapter,
+    seam: 'editor.structure.copy',
+    stage: 'effect',
+    detail: `the editor copied ${nodeIds.length} selected node(s)`,
+    run: () => provider.copy?.(nodeIds) ?? false,
+  });
+}
+
+async function clipboardStructureWrite(
+  adapter: AuthoringAdapter,
+  verb: 'cut' | 'paste',
+  detail: string,
+  run: () => StructuralClipboardOutcome,
+): Promise<false | WriteAck> {
+  const outcome = await recordAuthoringConsumerUse({
+    adapter,
+    seam: `editor.structure.${verb}`,
+    stage: 'effect',
+    detail,
+    run,
+  });
+  if (outcome === false) return false;
+  await structureWrite(adapter, verb, detail, () => outcome);
+  return outcome;
+}
+
+export function cutAuthoringNodes(
+  adapter: AuthoringAdapter,
+  nodeIds: readonly string[],
+): Promise<false | WriteAck> {
+  const provider = adapter.structure;
+  if (!provider?.cut) return Promise.resolve(false);
+  return clipboardStructureWrite(
+    adapter,
+    'cut',
+    `the editor cut ${nodeIds.length} selected node(s)`,
+    () => provider.cut?.(nodeIds) ?? false,
+  );
+}
+
+export function pasteAuthoringNodes(
+  adapter: AuthoringAdapter,
+  parentId: string | null,
+): Promise<false | WriteAck> {
+  const provider = adapter.structure;
+  if (!provider?.paste) return Promise.resolve(false);
+  return clipboardStructureWrite(
+    adapter,
+    'paste',
+    `the editor pasted nodes under ${parentId ?? 'the document root'}`,
+    () => provider.paste?.(parentId) ?? false,
+  );
+}
+
+/**
+ * ADAPTER-OWNED SPATIAL HANDLES, evidence-recorded — the same consumer wrapper
+ * every seam above gets, for the provider the 3D viewport raycasts.
+ *
+ * It lives HERE rather than beside the DOM world overlay it was written next
+ * to (`components/world-overlay-gestures.ts`) because its OTHER caller is
+ * `editor-viewport.ts`, and that surface must not import the overlay's graph:
+ * the overlay reaches the composite adapter, the react-world adapter and the
+ * UI source inspector, which is 124 files for a WeakMap and three recorded
+ * calls (ARCHITECTURE-CORE §Editor chrome, "the viewport stack is separable").
+ * Nothing about the wrapper was overlay-specific; this is its family.
+ */
+const recordedSpatialHandles = new WeakMap<
+  AuthoringAdapter,
+  { readonly provider: SpatialHandlesProvider; readonly recorded: SpatialHandlesProvider }
+>();
+
+/** Stable evidence-aware view of adapter-owned spatial handles. */
+export function spatialHandlesForAdapter(owner: AuthoringAdapter): SpatialHandlesProvider | null {
+  const provider = owner.spatialHandles;
+  if (!provider) return null;
+  const cached = recordedSpatialHandles.get(owner);
+  if (cached?.provider === provider) return cached.recorded;
+  const recorded: SpatialHandlesProvider = {
+    layers: (id) =>
+      recordAuthoringConsumerUse({
+        adapter: owner,
+        seam: 'editor.spatialHandles.layers',
+        stage: 'operation',
+        detail: `the viewport read adapter-owned spatial layers for ${id}`,
+        run: () => provider.layers(id),
+      }),
+    preview: (id, handleId, worldPosition) =>
+      recordAuthoringConsumerUse({
+        adapter: owner,
+        seam: 'editor.spatialHandles.preview',
+        stage: 'effect',
+        detail: `the viewport previewed spatial handle ${handleId} for ${id}`,
+        run: () => provider.preview(id, handleId, worldPosition),
+      }),
+    commit: (id, handleId, worldPosition) =>
+      recordAuthoringWriteConsumerUse({
+        adapter: owner,
+        seam: 'editor.spatialHandles.commit',
+        detail: `the viewport committed spatial handle ${handleId} for ${id}`,
+        run: () => provider.commit(id, handleId, worldPosition),
+      }),
+  };
+  recordedSpatialHandles.set(owner, { provider, recorded });
+  return recorded;
+}

package/src/authoring/css-numeric-style.ts

@@ -0,0 +1,97 @@
+/**
+ * THE ONE PLACE that knows a CSS numeric style value is not the same thing as
+ * its CSS TEXT.
+ *
+ * React's own rule (`dangerousStyleValue`): a NUMBER style value is emitted
+ * verbatim when it is `0` or the property is unitless, and suffixed with `px`
+ * otherwise. So `style={{ width: 300 }}` paints 300px while
+ * `style={{ width: '300' }}` paints NOTHING — the CSSOM rejects a unitless
+ * length and keeps the previous value.
+ *
+ * That is why the inspector's numeric descriptors must reach source as
+ * NUMBERS: stringifying `300` on the way to the writer produced
+ * `width: '300'`, which React passed through verbatim, which the CSSOM
+ * rejected — a write that changed source, changed nothing on screen, and
+ * acked `persisted: true`.
+ *
+ * The two consumers are the two halves of one write: the SOURCE (a bare `300`
+ * in the JSX style object, which React px-ifies at render) and the LIVE inline
+ * patch / CSS-file declaration (which are CSS TEXT and need the unit spelled).
+ * {@link cssTextForStyleValue} is the second half.
+ */
+
+/**
+ * Properties whose numeric value is unitless in CSS — the exact set the
+ * inspector's numeric widgets already print with no `px` suffix.
+ *
+ * Deliberately the SHIPPED list rather than React's full internal table: this
+ * set covers every `type: 'number'` descriptor the adapters declare
+ * (`STYLE_PROPERTIES`), and a descriptor added outside it would be wrong in
+ * the widget's suffix before it was wrong here.
+ */
+export const UNITLESS_NUMBER_PROPS: ReadonlySet<string> = new Set([
+  'opacity',
+  'zIndex',
+  'flexGrow',
+  'flexShrink',
+  // React's own unitless set includes these two, and px-ifying them writes
+  // INVALID CSS the browser silently drops (blind re-walk: extracting a
+  // class from an element with `fontWeight: 900` emitted
+  // `font-weight: 900px`, losing the weight). A numeric lineHeight is the
+  // unitless multiplier form — px-ifying it changes meaning, not just
+  // validity.
+  'fontWeight',
+  'lineHeight',
+]);
+
+/**
+ * THE READ HALF of the same rule: parse a real `CSSStyleDeclaration`'s
+ * length-property VALUE (always a unit-suffixed STRING, e.g. `"16px"` — CSSOM
+ * never hands back a bare number) into the plain number a `type: 'number'`
+ * `PropertyDescriptor` needs to render/edit correctly (`Inspector.tsx`'s
+ * generic renderer does `typeof v === 'number' ? … : 0` — without this parse,
+ * EVERY numeric style field would silently display `0` against a real browser
+ * DOM, even though plain-object `style: {}` fixtures never caught it, because
+ * a hand-built fixture can hold a bare JS number directly). Strips a trailing
+ * CSS unit (`px`/`em`/`rem`/`%`/`vh`/`vw`, mirroring `ui-source/writer.ts`'s
+ * own `LITERAL_RE` unit set); a value already handed over AS a number (or
+ * `undefined`/unset) passes through unchanged.
+ *
+ * It lived in `react-world-authoring-adapter.ts` until 2026-09-18 and moved
+ * here for the reason this module's header states — this is the one place that
+ * knows CSS numeric value and CSS text are different things — and because one
+ * host module that is NOT the React surface reads it: the overlay gesture bus
+ * (`components/world-overlay-gestures.ts`) parses a computed border width to
+ * place a resize handle. That single edge dragged the whole 3,848-line React
+ * root adapter into every editor boot (phase 1 of the open-source launch).
+ */
+export function numericStyleValue(raw: unknown): number | undefined {
+  if (typeof raw === 'number') return raw;
+  if (typeof raw !== 'string' || raw === '') return undefined;
+  const parsed = Number.parseFloat(raw);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+/** Numeric inspector edits change the magnitude of an authored CSS dimension.
+ * Keep relative units; ordinary React numbers and px values remain numbers. */
+export function preserveNumericStyleUnit(
+  value: string | number,
+  authored: unknown,
+): string | number {
+  if (typeof value !== 'number' || typeof authored !== 'string') return value;
+  const unit = authored.trim().match(/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?([a-z]+|%)$/i)?.[1];
+  return unit && unit.toLowerCase() !== 'px' ? `${value}${unit}` : value;
+}
+
+/**
+ * The CSS TEXT for a style value — React's `dangerousStyleValue` rule.
+ *
+ * A string passes through untouched (it is already CSS text — `'12px'`,
+ * `'var(--brand)'`, `'50%'`). A number becomes `${n}px` unless it is `0` or
+ * the property is unitless.
+ */
+export function cssTextForStyleValue(prop: string, value: string | number): string {
+  if (typeof value !== 'number') return value;
+  if (value === 0 || UNITLESS_NUMBER_PROPS.has(prop)) return String(value);
+  return `${value}px`;
+}