@brianmsm/quarto-bento 0.0.0-stage → 0.1.0

package/distribution/runtime/src/state/components.ts

@@ -0,0 +1,281 @@
+import { clone, targetKey, validateDoc } from "./json.ts";
+import {
+  type BentoDoc,
+  type ComponentCreation,
+  type ComponentFrame,
+  type ComponentProjection,
+  type ProjectState,
+  StateError,
+  type Target,
+} from "./types.ts";
+
+const object = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+function exact(value: Record<string, unknown>, keys: string[]) {
+  return Object.keys(value).length === keys.length &&
+    keys.every((key) => Object.hasOwn(value, key));
+}
+const sourceId = (value: unknown): value is string =>
+  typeof value === "string" && /^[A-Za-z][\w:.-]{0,119}$/.test(value);
+function validFrame(value: unknown): value is ComponentFrame {
+  return object(value) && exact(value, ["x", "y", "w", "h"]) &&
+    Object.values(value).every((number) =>
+      typeof number === "number" && Number.isFinite(number)
+    ) &&
+    Number(value.w) > 0 && Number(value.h) > 0;
+}
+/** Reserve source and generated identities, including hidden durable metadata. */
+export function componentIdentities(
+  id: string,
+  kind: "card" | "kpi",
+): string[] {
+  const roles = kind === "card"
+    ? ["title", "body"]
+    : ["label", "value", "detail"];
+  return [
+    id,
+    `${id}/qb-${kind}-background`,
+    ...roles.flatMap((role) => [
+      `${id}-${role}`,
+      ...(role === "title" ? [] : [`${id}-${role}/paragraph:1`]),
+    ]),
+  ];
+}
+export function validateComponentProjections(
+  value: unknown,
+  intents: ComponentCreation[] = [],
+): asserts value is ComponentProjection[] | undefined {
+  if (value === undefined) return;
+  const fail = (): never => {
+    throw new StateError(
+      "INVALID_COMPONENT_PROJECTION",
+      "Invalid, overlapping or unknown component projection metadata.",
+    );
+  };
+  if (!Array.isArray(value) || value.length + intents.length > 5000) fail();
+  const reserved = new Set(
+    intents.flatMap((intent) => componentIdentities(intent.id, intent.kind)),
+  );
+  for (const entry of value as ComponentProjection[]) {
+    if (
+      !object(entry) ||
+      !exact(entry, ["version", "id", "kind", "slideId", "frame"]) ||
+      entry.version !== 1 || !sourceId(entry.id) ||
+      !["card", "kpi"].includes(entry.kind) ||
+      typeof entry.slideId !== "string" || !entry.slideId ||
+      !validFrame(entry.frame)
+    ) fail();
+    const ids = componentIdentities(entry.id, entry.kind);
+    if (ids.some((id) => reserved.has(id))) fail();
+    ids.forEach((id) => reserved.add(id));
+  }
+}
+export function componentOwns(state: ProjectState, target: Target): boolean {
+  return !!state.componentCreations?.some((intent) =>
+    intent.slideId === target.slideId &&
+    (intent.backgroundId === target.elementId ||
+      intent.members.some((member) => member.nativeId === target.elementId))
+  );
+}
+/** Exact versioned ownership, never inferred from positions or native groupId. */
+export function validateComponentCreations(
+  value: unknown,
+  docId: string,
+): asserts value is ComponentCreation[] | undefined {
+  if (value === undefined) return;
+  const fail = (): never => {
+    throw new StateError(
+      "INVALID_COMPONENT_INTENT",
+      "Invalid, overlapping or unknown component creation metadata.",
+    );
+  };
+  if (!Array.isArray(value) || value.length > 128) fail();
+  const sources = new Set<string>(), native = new Set<string>();
+  for (const entry of value as ComponentCreation[]) {
+    if (
+      !object(entry) ||
+      !exact(entry, [
+        "version",
+        "id",
+        "kind",
+        "slideId",
+        "backgroundId",
+        "backgroundSnapshot",
+        "projectionFrame",
+        "restoreOrder",
+        "members",
+      ]) || entry.version !== 1 || !sourceId(entry.id) ||
+      !["card", "kpi"].includes(entry.kind) ||
+      typeof entry.slideId !== "string" || !entry.slideId ||
+      entry.backgroundId !== `${entry.id}/qb-${entry.kind}-background` ||
+      !Array.isArray(entry.members) || !validFrame(entry.projectionFrame)
+    ) fail();
+    const roles = entry.kind === "card"
+      ? ["title", "body"]
+      : ["label", "value", ...(entry.members.length === 3 ? ["detail"] : [])];
+    if (entry.members.length !== roles.length) fail();
+    if (sources.has(entry.id)) fail();
+    sources.add(entry.id);
+    for (const [index, member] of entry.members.entries()) {
+      if (
+        !object(member) ||
+        !exact(member, ["role", "sourceId", "nativeId", "snapshot"]) ||
+        member.role !== roles[index] ||
+        member.sourceId !== `${entry.id}-${member.role}` ||
+        member.nativeId !==
+          (member.role === "title"
+            ? member.sourceId
+            : `${member.sourceId}/paragraph:1`) ||
+        !object(member.snapshot) || member.snapshot.id !== member.nativeId ||
+        member.snapshot.type !== "text" ||
+        typeof member.snapshot.html !== "string" || sources.has(member.sourceId)
+      ) fail();
+      sources.add(member.sourceId);
+      // Implicit paragraph IDs are source identities too.
+      if (member.nativeId !== member.sourceId) {
+        if (sources.has(member.nativeId)) fail();
+        sources.add(member.nativeId);
+      }
+    }
+    if (
+      !object(entry.backgroundSnapshot) ||
+      entry.backgroundSnapshot.id !== entry.backgroundId ||
+      entry.backgroundSnapshot.type !== "shape" ||
+      entry.backgroundSnapshot.shape !== "rect"
+    ) fail();
+    const memberIds = [
+      entry.backgroundId,
+      ...entry.members.map((member) => member.nativeId),
+    ];
+    if (
+      !Array.isArray(entry.restoreOrder) || entry.restoreOrder.length > 5000 ||
+      entry.restoreOrder.some((id) => typeof id !== "string" || !id) ||
+      new Set(entry.restoreOrder).size !== entry.restoreOrder.length ||
+      memberIds.some((id) => !entry.restoreOrder.includes(id))
+    ) fail();
+    const snapshots = [
+      entry.backgroundSnapshot,
+      ...entry.members.map((member) => member.snapshot),
+    ];
+    for (const snapshot of snapshots) {
+      const key = targetKey({ slideId: entry.slideId, elementId: snapshot.id });
+      if (native.has(key)) fail();
+      native.add(key);
+    }
+    validateDoc({
+      docId,
+      slides: [{ id: entry.slideId, elements: snapshots }],
+    });
+  }
+}
+/** Last-present snapshots survive missing fields and the containing slide's deletion. */
+export function captureComponentSnapshots(
+  state: ProjectState,
+  edited: BentoDoc,
+): void {
+  state.componentCreations = state.componentCreations?.filter((intent) => {
+    const slide = edited.slides.find((slide) => slide.id === intent.slideId);
+    if (!slide) return true;
+    const ids = [
+      intent.backgroundId,
+      ...intent.members.map((member) => member.nativeId),
+    ];
+    const known = slide.elements.filter((element) => ids.includes(element.id));
+    const extra = slide.elements.some((element) =>
+      element.groupId === intent.id && !ids.includes(element.id)
+    );
+    if (!known.length && !extra) return false;
+    if (ids.every((id) => known.some((element) => element.id === id))) {
+      intent.restoreOrder = slide.elements.map((element) => element.id);
+    }
+    for (const member of intent.members) {
+      const current = known.find((element) => element.id === member.nativeId);
+      if (current?.type === "text" && typeof current.html === "string") {
+        member.snapshot = clone(current);
+      }
+    }
+    const background = known.find((element) =>
+      element.id === intent.backgroundId
+    );
+    if (background?.type === "shape" && background.shape === "rect") {
+      intent.backgroundSnapshot = clone(background);
+    }
+    return true;
+  });
+  if (!state.componentCreations?.length) delete state.componentCreations;
+}
+export function componentProblems(
+  state: ProjectState,
+  intent: ComponentCreation,
+): string[] {
+  const slide = state.emitted.slides.find((slide) =>
+    slide.id === intent.slideId
+  );
+  if (!slide) {
+    return [
+      "La diapositiva está pendiente de eliminación: restáurala primero o revisa su eliminación.",
+    ];
+  }
+  const ids = [
+    intent.backgroundId,
+    ...intent.members.map((member) => member.nativeId),
+  ];
+  const problems: string[] = [];
+  const background = slide.elements.find((element) =>
+    element.id === intent.backgroundId
+  );
+  if (
+    !background || background.type !== "shape" || background.shape !== "rect"
+  ) problems.push("Falta el fondo rectangular original o cambió su tipo.");
+  for (const member of intent.members) {
+    const element = slide.elements.find((element) =>
+      element.id === member.nativeId
+    );
+    if (
+      !element || element.type !== "text" || typeof element.html !== "string"
+    ) {
+      problems.push(
+        `Falta el campo ${
+          {
+            title: "título",
+            body: "cuerpo",
+            label: "etiqueta",
+            value: "valor",
+            detail: "detalle",
+          }[member.role]
+        } original o cambió su tipo.`,
+      );
+    }
+    const pending = state.pending.find((change) =>
+      change.kind === "create-element" &&
+      change.target.slideId === intent.slideId &&
+      change.target.elementId === member.nativeId
+    );
+    if (
+      element &&
+      (!pending || pending.origin !== "authored" || pending.before.present)
+    ) {
+      problems.push(
+        `El campo ${
+          {
+            title: "título",
+            body: "cuerpo",
+            label: "etiqueta",
+            value: "valor",
+            detail: "detalle",
+          }[member.role]
+        } no conserva una creación pendiente verificable.`,
+      );
+    }
+  }
+  if (
+    slide.elements.some((element) =>
+      element.groupId === intent.id && !ids.includes(element.id)
+    )
+  ) {
+    problems.push(
+      "Hay objetos adicionales en el grupo. Sepáralos o descarta el componente pendiente.",
+    );
+  }
+  return problems;
+}

package/distribution/runtime/src/state/graphs.ts

@@ -0,0 +1,200 @@
+/** Checked relationships for source graphs only; ordinary decorations remain visual. */
+import {
+  type BentoDoc,
+  type Change,
+  type JsonObject,
+  type Provenance,
+  type ProvenanceMap,
+  StateError,
+} from "./types.ts";
+
+export interface GraphReceipt extends JsonObject {
+  version: 1;
+  kind: "diagram" | "timeline";
+  componentId: string;
+  sourceId: string;
+  role: "node" | "milestone" | "edge" | "timeline-link";
+  nodeIds: string[];
+}
+export function graphReceipt(
+  provenance?: Provenance,
+): GraphReceipt | undefined {
+  const graph = provenance?.source?.graph;
+  if (graph === undefined) return undefined;
+  if (
+    !graph || typeof graph !== "object" || Array.isArray(graph) ||
+    graph.version !== 1 ||
+    !["diagram", "timeline"].includes(String(graph.kind)) ||
+    typeof graph.componentId !== "string" ||
+    typeof graph.sourceId !== "string" ||
+    !["node", "milestone", "edge", "timeline-link"].includes(
+      String(graph.role),
+    ) ||
+    !Array.isArray(graph.nodeIds) ||
+    graph.nodeIds.some((id) => typeof id !== "string") ||
+    new Set(graph.nodeIds).size !== graph.nodeIds.length
+  ) {
+    throw new StateError(
+      "INVALID_GRAPH_PROVENANCE",
+      "A source graph requires a checked bounded membership receipt.",
+    );
+  }
+  return graph as GraphReceipt;
+}
+export function graphRelationshipPath(
+  provenance: Provenance | undefined,
+  path: string[],
+): boolean {
+  const graph = graphReceipt(provenance);
+  return !!graph && ["edge", "timeline-link"].includes(graph.role) &&
+    ["from", "to"].includes(path[0]) && (path.length === 1 || path[1] === "el");
+}
+function fail(code: string, message: string): never {
+  throw new StateError(code, message);
+}
+/** Capture preserves missing known source parts as pending; publication cannot emit dangling native graphs. */
+export function assertGraphDocument(
+  document: BentoDoc,
+  provenance: ProvenanceMap,
+  options: {
+    baseline?: BentoDoc;
+    capture?: boolean;
+    strict?: boolean;
+    pending?: Change[];
+  } = {},
+): void {
+  const partial = options.capture || options.strict === false;
+  for (const slide of document.slides) {
+    const proofs = Object.entries(provenance).flatMap(([key, source]) => {
+      const graph = graphReceipt(source);
+      if (!graph) return [];
+      const [slideId, elementId] = JSON.parse(key) as [
+        string | null,
+        string | null,
+      ];
+      return slideId === slide.id && elementId && graph
+        ? [{ elementId, graph }]
+        : [];
+    });
+    for (const { elementId, graph } of proofs) {
+      const element = slide.elements.find((element) =>
+        element.id === elementId
+      );
+      if (!element) {
+        if (!partial) {
+          fail(
+            "GRAPH_PENDING_DELETION",
+            "A source graph part is removed only in Bento; restore it or synchronize an explicitly supported source operation before rendering.",
+          );
+        }
+        continue;
+      }
+      if (
+        graph.labelId &&
+        !slide.elements.some((element) => element.id === graph.labelId)
+      ) {
+        if (!partial) {
+          fail(
+            "GRAPH_PENDING_DELETION",
+            "A source graph label is pending deletion; preserve/review the source component before publishing.",
+          );
+        }
+      }
+      if (
+        !partial && graph.labelId &&
+        slide.elements.find((label) => label.id === graph.labelId)?.type !==
+          "text"
+      ) {
+        fail(
+          "GRAPH_PENDING_STRUCTURE",
+          "The native source graph label changed renderer; restore its text object before publishing.",
+        );
+      }
+      if (graph.role === "node" || graph.role === "milestone") {
+        if (
+          !partial &&
+          (element.type !== "shape" ||
+            ["line", "path"].includes(String(element.shape)))
+        ) {
+          fail(
+            "GRAPH_PENDING_STRUCTURE",
+            "The native source node changed to an incompatible renderer; restore the node shape before publishing.",
+          );
+        }
+        continue;
+      }
+      if (!partial && (element.type !== "shape" || element.shape !== "line")) {
+        fail(
+          "GRAPH_PENDING_STRUCTURE",
+          "The native source connector changed its renderer; restore its line shape before publishing the relationship.",
+        );
+      }
+      for (const endpoint of ["from", "to"] as const) {
+        const value = element[endpoint];
+        const reference =
+          value && typeof value === "object" && !Array.isArray(value)
+            ? value.el
+            : undefined;
+        if (reference === undefined && partial) continue; // Native detachment remains pending, never style.
+        if (typeof reference !== "string" || !reference) {
+          fail(
+            "GRAPH_ENDPOINT_REQUIRED",
+            "Source graph connectors need both explicit native node endpoints; restore or review the detached endpoint.",
+          );
+        }
+        const expected = String(graph[endpoint]) + "/qb-node";
+        if (
+          graph.role === "timeline-link" && !partial && reference !== expected
+        ) {
+          fail(
+            "UNSUPPORTED_TIMELINE_RELATION",
+            "Timeline links derive from lexical QMD order. Native endpoint edits remain pending; restore them or reorder original milestone blocks.",
+          );
+        }
+        const targetProof = proofs.find((proof) =>
+          proof.elementId === reference
+        )?.graph;
+        const target = slide.elements.find((element) =>
+          element.id === reference
+        );
+        if (
+          !targetProof || !["node", "milestone"].includes(targetProof.role) ||
+          targetProof.kind !== graph.kind ||
+          targetProof.componentId !== graph.componentId ||
+          !graph.nodeIds.includes(targetProof.sourceId) ||
+          reference !== targetProof.sourceId + "/qb-node"
+        ) {
+          fail(
+            "GRAPH_ENDPOINT_SCOPE",
+            "A source connector can reference only a direct source node shape in its own original graph and slide.",
+          );
+        }
+        if (!target) {
+          const baseline = options.baseline?.slides.find((baseline) =>
+            baseline.id === slide.id
+          );
+          const previous = baseline?.elements.find((previous) =>
+            previous.id === elementId
+          )?.[endpoint];
+          const unchanged = previous && typeof previous === "object" &&
+            !Array.isArray(previous) && previous.el === reference;
+          if (!partial || !unchanged) {
+            fail(
+              "GRAPH_DANGLING_ENDPOINT",
+              "The referenced native node is absent; restore the pending node before publishing this graph.",
+            );
+          }
+        }
+      }
+      const from = element.from as JsonObject | undefined,
+        to = element.to as JsonObject | undefined;
+      if (from?.el && from.el === to?.el) {
+        fail(
+          "GRAPH_ENDPOINT_SCOPE",
+          "Self edges are outside the bounded source diagram contract.",
+        );
+      }
+    }
+  }
+  // A removed whole source slide is already a separately controlled pending action.
+}

package/distribution/runtime/src/state/json.ts

@@ -0,0 +1,162 @@
+import {
+  type BentoDoc,
+  type Field,
+  type Json,
+  type JsonObject,
+  StateError,
+  type Target,
+  type Value,
+} from "./types.ts";
+
+export function assertJson(value: unknown, depth = 0): asserts value is Json {
+  if (depth > 100) {
+    throw new StateError("INVALID_JSON", "JSON nesting exceeds 100 levels.");
+  }
+  if (
+    value === null || typeof value === "string" || typeof value === "boolean"
+  ) return;
+  if (typeof value === "number" && Number.isFinite(value)) return;
+  if (Array.isArray(value)) {
+    for (const item of value) assertJson(item, depth + 1);
+    return;
+  }
+  if (
+    typeof value !== "object" ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) throw new StateError("INVALID_JSON", "Expected plain JSON data.");
+  for (const [key, item] of Object.entries(value)) {
+    if (["__proto__", "prototype", "constructor"].includes(key)) {
+      throw new StateError("UNSAFE_KEY", `Unsafe JSON key: ${key}`);
+    }
+    assertJson(item, depth + 1);
+  }
+}
+export function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+export function canonical(value: unknown): string {
+  if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
+  if (value && typeof value === "object") {
+    return "{" + Object.keys(value).sort().map((k) =>
+      JSON.stringify(k) + ":" + canonical((value as Record<string, unknown>)[k])
+    ).join(",") + "}";
+  }
+  return JSON.stringify(value);
+}
+export function equal(a: unknown, b: unknown): boolean {
+  return canonical(a) === canonical(b);
+}
+export function targetKey(target: Target): string {
+  return JSON.stringify([target.slideId ?? null, target.elementId ?? null]);
+}
+export function validateDoc(doc: unknown): asserts doc is BentoDoc {
+  assertJson(doc);
+  if (
+    !doc || Array.isArray(doc) || typeof doc !== "object" ||
+    typeof doc.docId !== "string" || !doc.docId || !Array.isArray(doc.slides)
+  ) {
+    throw new StateError(
+      "INVALID_DOCUMENT",
+      "Document requires docId and slides.",
+    );
+  }
+  const slideIds = new Set();
+  for (const slide of doc.slides) {
+    if (
+      !slide || Array.isArray(slide) || typeof slide !== "object" ||
+      typeof slide.id !== "string" || !slide.id ||
+      !Array.isArray(slide.elements)
+    ) {
+      throw new StateError(
+        "INVALID_ID",
+        "Each slide requires a stable nonempty id and elements array.",
+      );
+    }
+    if (slideIds.has(slide.id)) {
+      throw new StateError("DUPLICATE_ID", `Duplicate slide ID ${slide.id}`);
+    }
+    slideIds.add(slide.id);
+    const ids = new Set();
+    for (const el of slide.elements) {
+      if (
+        !el || Array.isArray(el) || typeof el !== "object" ||
+        typeof el.id !== "string" || !el.id || typeof el.type !== "string" ||
+        !el.type
+      ) {
+        throw new StateError(
+          "INVALID_ID",
+          "Each element requires a stable nonempty id and type.",
+        );
+      }
+      if (ids.has(el.id)) {
+        throw new StateError(
+          "DUPLICATE_ID",
+          `Duplicate element ID ${el.id} on ${slide.id}`,
+        );
+      }
+      ids.add(el.id);
+    }
+  }
+}
+export function entity(doc: BentoDoc, target: Target): JsonObject | undefined {
+  if (!target.slideId) return doc;
+  const slide = doc.slides.find((s) => s.id === target.slideId);
+  return target.elementId
+    ? slide?.elements.find((e) => e.id === target.elementId)
+    : slide;
+}
+export function get(object: JsonObject | undefined, path: string[]): Value {
+  let value: Json | undefined = object;
+  for (const key of path) {
+    if (
+      !value || typeof value !== "object" || Array.isArray(value) ||
+      !Object.hasOwn(value, key)
+    ) return { present: false };
+    value = value[key];
+  }
+  return value === undefined
+    ? { present: false }
+    : { present: true, value: clone(value) };
+}
+export function set(object: JsonObject, path: string[], value: Value): void {
+  if (
+    !path.length ||
+    path.some((k) => ["__proto__", "constructor", "prototype"].includes(k))
+  ) throw new StateError("INVALID_PATH", "Unsafe or empty property path.");
+  let cursor = object;
+  for (const key of path.slice(0, -1)) {
+    if (
+      !cursor[key] || typeof cursor[key] !== "object" ||
+      Array.isArray(cursor[key])
+    ) cursor[key] = {};
+    cursor = cursor[key] as JsonObject;
+  }
+  if (value.present) cursor[path.at(-1)!] = clone(value.value!);
+  else delete cursor[path.at(-1)!];
+}
+export function fields(
+  before: JsonObject,
+  after: JsonObject,
+  skip: string[] = [],
+): Field[] {
+  const result: Field[] = [];
+  function visit(a: JsonObject, b: JsonObject, path: string[]) {
+    for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+      if (!path.length && skip.includes(key)) continue;
+      const av = a[key], bv = b[key], next = [...path, key];
+      if (equal(av, bv)) continue;
+      if (
+        av && bv && typeof av === "object" && typeof bv === "object" &&
+        !Array.isArray(av) && !Array.isArray(bv)
+      ) visit(av, bv, next);
+      else {result.push({
+          path: next,
+          value: bv === undefined
+            ? { present: false }
+            : { present: true, value: clone(bv) },
+        });}
+    }
+  }
+  visit(before, after, []);
+  return result;
+}