@vgai/editor 0.2.0

package/src/ui-source/source-write-backend.ts

@@ -0,0 +1,203 @@
+/**
+ * SourceWriteBackend — the pending-write flush contract for JSX source edits (T3.2
+ * slice 3, design `docs/PERSISTENCE-PROVIDER-DESIGN.md` §4).
+ *
+ * `UIAuthoringAdapter.persistence.save()` is the de-stub target for this seam. What
+ * we found investigating the CURRENT write lifecycle (see `source-edit-panel.tsx`):
+ * there is NO pending-write queue — every source edit (a style tweak, a struct op)
+ * writes to disk IMMEDIATELY via a raw `fetch` call the instant the user commits it
+ * (Enter / blur), server-side through the SAME surgical writer used in unit tests
+ * (`ui-source/writer.ts`, invoked by `vite-plugin-ui-oid.ts`'s dev-server
+ * middleware). So `save()` has nothing to flush; it is an honest no-op REGARDLESS of
+ * whether a backend is wired (see `ui-authoring-adapter.ts`). This seam exists so:
+ *   - the HTTP wire shape is reachable/testable through an injectable interface
+ *     instead of a bare `fetch` scattered in the adapter, and
+ *   - a future batching/offline queue (if one is ever built) has somewhere honest
+ *     to route writes — this file does NOT invent that queue.
+ *
+ * The browser/hosted tier (no dev server, e.g. a `--mode web` hosted build) has NO
+ * implementation here. Backend absence is surfaced through
+ * `persistence.destination`, NOT by flipping `capabilities.persist` to false —
+ * see `ui-authoring-adapter.ts`'s doc comment for why that flag deliberately
+ * stays `true` (it also gates the separate ui-tree→`.vscn` path). We do NOT
+ * fake a save.
+ *
+ * Explicit non-goal (design §6): the vite plugin's raw `node:fs` writes are
+ * server-side and stay exactly as they are — this seam is the CLIENT-facing
+ * contract in front of them, not a reroute of their internals through
+ * `StorageBackend`.
+ *
+ * `index()` (T6.2 slice 2, `docs/REACT-WORLD-DESIGN.md` §1.D) is the read-side
+ * sibling added for `ReactWorldAuthoringAdapter`'s node labeling
+ * (`component:tag`): it exposes the SAME `/__ui-source/index` GET endpoint
+ * `vite-plugin-ui-oid.ts` already serves (previously only fetched ad hoc by
+ * `source-edit-panel.tsx`) through this one backend seam, rather than a second
+ * bespoke fetch call.
+ */
+
+import type { OidEntry } from './oid-transform';
+
+/** The source-write operations (+ the OID index read) the dev-server middleware
+ *  already exposes. */
+export interface SourceWriteBackend {
+  /** Surgical inline-style/className edit — the `/__ui-source/write` shape.
+   *  `appended` (D-A1, wave 13) is true only when the write took the writer's
+   *  APPEND branch (no prior literal for this prop) — see
+   *  `ReactWorldAuthoringAdapter.writeStyle`'s append-aware undo (D-A4). */
+  writeStyle(
+    oid: string,
+    prop: string,
+    value: string,
+  ): Promise<{
+    changed: boolean;
+    dynamic?: boolean;
+    route?: string;
+    error?: string;
+    appended?: boolean;
+  }>;
+  /**
+   * D-A3 (wave 13): surgically REMOVE an appended inline-style property — the
+   * correct undo for a write that took the append branch (`appended: true`).
+   * Posts the SAME `/__ui-source/write` endpoint `writeStyle` uses, with the
+   * `value: null` removal sentinel the middleware routes to `removeInlineStyle`.
+   */
+  removeStyle(
+    oid: string,
+    prop: string,
+  ): Promise<{ changed: boolean; route?: string; error?: string }>;
+  /** Surgical CSS-FILE edit (Cap 2) — the `/__ui-source/css` shape. The client resolves
+   *  the target rule (source file + selector) from live matched-rule data and sends it;
+   *  the server edits that file in place. `generated: true` means the selector was not
+   *  found in source (generated CSS) — the caller re-routes to class/inline.
+   *  Optional: only a dev-server-backed implementation serves it. */
+  writeCss?(
+    file: string,
+    selector: string,
+    prop: string,
+    value: string,
+  ): Promise<{ changed: boolean; generated?: boolean; error?: string }>;
+  /** Text-content edit (Cap 3) — the `/__ui-source/text` shape. Replaces a leaf element's
+   *  pure-text body; `dynamic: true` means the body has an expression/children (refused).
+   *  `prevText` is the editable text before the edit (for the undo inverse). Optional:
+   *  only a dev-server-backed implementation serves it. */
+  writeText?(
+    oid: string,
+    text: string,
+  ): Promise<{ changed: boolean; dynamic?: boolean; prevText?: string | null; error?: string }>;
+  /** Component prop / attribute edit (Cap 4) — the `/__ui-source/prop` shape. `oid` is the
+   *  CALL-SITE oid (the `<Component …>` tag). `dynamic: true` ⇒ the prop is a non-literal
+   *  expression (refused). Optional: only a dev-server-backed implementation serves it. */
+  writeProp?(
+    oid: string,
+    prop: string,
+    value: string,
+  ): Promise<{ changed: boolean; dynamic?: boolean; error?: string }>;
+  /**
+   * Structural source edit — the `/__ui-source/struct` shape. Ops: `delete`, `duplicate`,
+   * `wrap`/`unwrap`, `create`, `reorder`, `reparent` (Cap 5). Multi-oid ops pass the
+   * companion oid(s) + optional `wrapperTag` via `opts`.
+   *
+   * D-1 (Phase D, spec27 §2): when `changed`, the server ALSO returns the whole
+   * touched file's `prevSource`/`newSource` (before/after this op) plus their
+   * `prevSha`/`newSha` (sha256, server-computed) — the checksum-guarded
+   * whole-file snapshot inverse `ReactWorldAuthoringAdapter.structOp` needs to
+   * push ONE undo/redo entry per structural op (a per-OID inverse is unsound
+   * here: OIDs are `file:component:tag:nthOccurrence` content signatures,
+   * reorder/delete reassign occurrence indices, and delete has no inverse
+   * payload of its own). These fields are absent when `changed` is false, and
+   * on an implementation that predates D-1 (a bare `{changed}` mock) — either
+   * way the caller degrades to "not undoable" rather than crashing.
+   */
+  writeStruct(
+    oid: string,
+    op: string,
+    opts?: { targetOid?: string; parentOid?: string; wrapperTag?: string },
+  ): Promise<{
+    changed: boolean;
+    error?: string;
+    file?: string;
+    prevSource?: string;
+    newSource?: string;
+    prevSha?: string;
+    newSha?: string;
+  }>;
+  /**
+   * Batched structural delete — delete-order-residual fix (bug-panel follow-up to
+   * the multi-delete corruption fix, 50f90a6d), the `/__ui-source/struct-many`
+   * shape. Delete-only today (`op` must be `'delete'`). Unlike N separate
+   * `writeStruct(oid, 'delete')` calls, the server resolves every `oids` entry's
+   * offset against ONE shared file snapshot and applies them all in a single write
+   * — sound and CALLER-ORDER-INDEPENDENT (see `handleStructMany`'s doc comment,
+   * `vite-plugin-ui-oid.ts`): the caller does not need to sort `oids` into any
+   * particular order, source or otherwise. Same response shape as `writeStruct`
+   * (one `prevSource`/`newSource`/`prevSha`/`newSha` snapshot for the whole batch
+   * — one undo entry, not N). Optional: only a dev-server-backed implementation
+   * serves it; its absence is how `ReactWorldAuthoringAdapter` honestly degrades
+   * `structure.removeMany` to absent (the shell then falls back to
+   * `deleteSelection`'s per-id loop, unchanged).
+   */
+  writeStructMany?(
+    oids: readonly string[],
+    op: string,
+  ): Promise<{
+    changed: boolean;
+    error?: string;
+    file?: string;
+    prevSource?: string;
+    newSource?: string;
+    prevSha?: string;
+    newSha?: string;
+  }>;
+  /**
+   * D-1 — the checksum-guarded whole-file restore: the undo/redo inverse for a
+   * structural edit. Writes `source` to `file` ONLY if the file's CURRENT
+   * content hashes (sha256) to `ifMatchSha`; refuses — `restored: false`,
+   * NEVER writes — otherwise (the file changed out from under the timeline
+   * since, e.g. a hand-edit, or an out-of-order restore). The caller never
+   * computes a hash itself; it only echoes back one `writeStruct` already
+   * handed it (`prevSha`/`newSha`) — see that method's doc comment. Optional:
+   * only a dev-server-backed implementation can serve it — its absence is how
+   * a caller without whole-file-restore support (a legacy mock, a future
+   * non-dev-server tier) honestly degrades a structural op to "not undoable"
+   * instead of assuming a restore path that isn't there.
+   */
+  restoreSource?(
+    file: string,
+    source: string,
+    ifMatchSha: string,
+  ): Promise<{ restored: boolean; sha?: string; error?: string }>;
+  /** The whole OID → source-location index — the `/__ui-source/index` shape.
+   *  Optional: only a dev-server-backed implementation can serve it. */
+  index?(): Promise<Record<string, OidEntry>>;
+}
+
+async function postJson<T>(url: string, body: unknown): Promise<T> {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return (await res.json()) as T;
+}
+
+/** Wraps the EXISTING `/__ui-source/write` + `/__ui-source/struct` dev-server
+ *  endpoints (see `vite-plugin-ui-oid.ts`) — the dev-server-backed tier. */
+export function createHttpSourceWriteBackend(): SourceWriteBackend {
+  return {
+    writeStyle: (oid, prop, value) => postJson('/__ui-source/write', { oid, prop, value }),
+    // D-A3: the removal sentinel — same endpoint, `value: null`.
+    removeStyle: (oid, prop) => postJson('/__ui-source/write', { oid, prop, value: null }),
+    writeCss: (file, selector, prop, value) =>
+      postJson('/__ui-source/css', { file, selector, prop, value }),
+    writeText: (oid, text) => postJson('/__ui-source/text', { oid, text }),
+    writeProp: (oid, prop, value) => postJson('/__ui-source/prop', { oid, prop, value }),
+    writeStruct: (oid, op, opts) => postJson('/__ui-source/struct', { oid, op, ...opts }),
+    writeStructMany: (oids, op) => postJson('/__ui-source/struct-many', { oids, op }),
+    restoreSource: (file, source, ifMatchSha) =>
+      postJson('/__ui-source/restore', { file, source, ifMatchSha }),
+    index: async () => {
+      const res = await fetch('/__ui-source/index');
+      return (await res.json()) as Record<string, OidEntry>;
+    },
+  };
+}

package/src/ui-source/tailwind-map.ts

@@ -0,0 +1,174 @@
+/**
+ * CSS property → Tailwind class converter (Cap 6 of the React visual-edit parity port,
+ * `docs/REACT-VISUAL-EDIT-PARITY.md`). A faithful port of `../../../visual-edit/tailwind-
+ * map.ts`: the ~30 grouped-inspector properties, using NAMED utilities where a keyword maps
+ * cleanly (`flex`, `justify-center`, `font-bold`, `rounded-full`, `border-2`) and arbitrary
+ * values (`w-[200px]`, `bg-[#059669]`) as the universal lossless fallback.
+ *
+ * This is the NAMED-utility converter — complementary to `writer.ts`'s `cssToUtilityClass`,
+ * which stays on the strictly-lossless arbitrary+type-hint scheme the source-write dedupe
+ * (`classGroup`) depends on. Use this when a human-readable named utility is preferred over
+ * round-trip-exact arbitrary values.
+ */
+
+/** Sanitize a CSS value for use inside Tailwind's `[...]` arbitrary brackets (no spaces;
+ *  collapse `, ` → `,` first, e.g. `rgb(0, 0, 0)` → `rgb(0,_0,_0)`). */
+function sanitize(val: string): string {
+  return val.replace(/,\s+/g, ',').replace(/\s+/g, '_');
+}
+
+/** Empty / non-meaningful values that shouldn't generate a class. */
+function isEmpty(val: string): boolean {
+  return !val || val === 'normal' || val === 'auto' || val === 'none' || val === '';
+}
+
+const DISPLAY_MAP: Record<string, string> = {
+  block: 'block',
+  flex: 'flex',
+  grid: 'grid',
+  inline: 'inline',
+  'inline-block': 'inline-block',
+  'inline-flex': 'inline-flex',
+  'inline-grid': 'inline-grid',
+  none: 'hidden',
+  contents: 'contents',
+};
+const FLEX_DIRECTION_MAP: Record<string, string> = {
+  row: 'flex-row',
+  column: 'flex-col',
+  'row-reverse': 'flex-row-reverse',
+  'column-reverse': 'flex-col-reverse',
+};
+const JUSTIFY_CONTENT_MAP: Record<string, string> = {
+  'flex-start': 'justify-start',
+  'flex-end': 'justify-end',
+  center: 'justify-center',
+  'space-between': 'justify-between',
+  'space-around': 'justify-around',
+  'space-evenly': 'justify-evenly',
+  start: 'justify-start',
+  end: 'justify-end',
+  stretch: 'justify-stretch',
+};
+const ALIGN_ITEMS_MAP: Record<string, string> = {
+  'flex-start': 'items-start',
+  'flex-end': 'items-end',
+  center: 'items-center',
+  baseline: 'items-baseline',
+  stretch: 'items-stretch',
+  start: 'items-start',
+  end: 'items-end',
+};
+const TEXT_ALIGN_MAP: Record<string, string> = {
+  left: 'text-left',
+  center: 'text-center',
+  right: 'text-right',
+  justify: 'text-justify',
+  start: 'text-start',
+  end: 'text-end',
+};
+const OVERFLOW_MAP: Record<string, string> = {
+  visible: 'overflow-visible',
+  hidden: 'overflow-hidden',
+  scroll: 'overflow-scroll',
+  auto: 'overflow-auto',
+  clip: 'overflow-clip',
+};
+const BORDER_STYLE_MAP: Record<string, string> = {
+  none: 'border-none',
+  solid: 'border-solid',
+  dashed: 'border-dashed',
+  dotted: 'border-dotted',
+  double: 'border-double',
+  hidden: 'border-hidden',
+};
+const FONT_WEIGHT_MAP: Record<string, string> = {
+  '100': 'font-thin',
+  '200': 'font-extralight',
+  '300': 'font-light',
+  '400': 'font-normal',
+  '500': 'font-medium',
+  '600': 'font-semibold',
+  '700': 'font-bold',
+  '800': 'font-extrabold',
+  '900': 'font-black',
+  normal: 'font-normal',
+  bold: 'font-bold',
+};
+
+type Converter = (value: string) => string;
+const arb =
+  (prefix: string): Converter =>
+  (v) =>
+    isEmpty(v) ? '' : `${prefix}-[${sanitize(v)}]`;
+
+/** camelCase CSS property → a Tailwind-class converter (empty string ⇒ no class). */
+const converters: Record<string, Converter> = {
+  display: (v) => DISPLAY_MAP[v] ?? '',
+  flexDirection: (v) => FLEX_DIRECTION_MAP[v] ?? '',
+  justifyContent: (v) => JUSTIFY_CONTENT_MAP[v] ?? '',
+  alignItems: (v) => ALIGN_ITEMS_MAP[v] ?? '',
+  gap: arb('gap'),
+  width: arb('w'),
+  height: arb('h'),
+  minWidth: arb('min-w'),
+  minHeight: arb('min-h'),
+  maxWidth: (v) => (v === 'none' ? 'max-w-none' : arb('max-w')(v)),
+  maxHeight: (v) => (v === 'none' ? 'max-h-none' : arb('max-h')(v)),
+  marginTop: (v) => `mt-[${sanitize(v)}]`,
+  marginRight: (v) => `mr-[${sanitize(v)}]`,
+  marginBottom: (v) => `mb-[${sanitize(v)}]`,
+  marginLeft: (v) => `ml-[${sanitize(v)}]`,
+  paddingTop: (v) => `pt-[${sanitize(v)}]`,
+  paddingRight: (v) => `pr-[${sanitize(v)}]`,
+  paddingBottom: (v) => `pb-[${sanitize(v)}]`,
+  paddingLeft: (v) => `pl-[${sanitize(v)}]`,
+  fontSize: arb('text'),
+  fontWeight: (v) => FONT_WEIGHT_MAP[v] ?? (isEmpty(v) ? '' : `font-[${sanitize(v)}]`),
+  lineHeight: arb('leading'),
+  textAlign: (v) => TEXT_ALIGN_MAP[v] ?? '',
+  color: (v) => namedColor('text', v) ?? arb('text')(v),
+  backgroundColor: (v) => namedColor('bg', v) ?? arb('bg')(v),
+  borderColor: (v) => namedColor('border', v) ?? arb('border')(v),
+  borderWidth: (v) => BORDER_WIDTH_MAP[v] ?? (isEmpty(v) ? '' : `border-[${sanitize(v)}]`),
+  borderStyle: (v) => BORDER_STYLE_MAP[v] ?? '',
+  borderRadius: (v) =>
+    v === '0' || v === '0px'
+      ? 'rounded-none'
+      : v === '9999px' || v === '100%'
+        ? 'rounded-full'
+        : arb('rounded')(v),
+  overflow: (v) => OVERFLOW_MAP[v] ?? '',
+  opacity: (v) => (v === '1' ? 'opacity-100' : v === '0' ? 'opacity-0' : arb('opacity')(v)),
+  boxShadow: (v) => (v === 'none' ? 'shadow-none' : arb('shadow')(v)),
+};
+
+const BORDER_WIDTH_MAP: Record<string, string> = {
+  '0': 'border-0',
+  '0px': 'border-0',
+  '1px': 'border',
+  '2px': 'border-2',
+  '4px': 'border-4',
+  '8px': 'border-8',
+};
+
+/** The few keyword colors Tailwind names directly (else the caller falls back to arbitrary). */
+function namedColor(prefix: string, v: string): string | null {
+  if (v === 'transparent') return `${prefix}-transparent`;
+  if (v === 'inherit') return `${prefix}-inherit`;
+  if (v === 'currentColor' || v === 'currentcolor') return `${prefix}-current`;
+  return null;
+}
+
+/** Convert a single CSS `prop:value` to a Tailwind class (`''` if unmapped/empty). */
+export function cssToTailwindClass(prop: string, value: string): string {
+  return converters[prop]?.(value.trim()) ?? '';
+}
+
+/** Convert a record of CSS changes to a space-separated Tailwind class string. */
+export function cssChangesToTailwindClasses(changes: Record<string, string>): string {
+  return Object.entries(changes)
+    .map(([prop, value]) => cssToTailwindClass(prop, value))
+    .filter(Boolean)
+    .join(' ');
+}