@brianmsm/quarto-bento 0.0.0-stage → 0.1.0

package/distribution/runtime/src/core/kpi-appearance.ts

@@ -0,0 +1,205 @@
+/** Previously verified source roles can supply visual typography, never meaning. */
+import { clone, type ProjectState, targetKey } from "../state/mod.ts";
+import type { SourceDocument } from "../source/mod.ts";
+import { verifiedSourceSlide } from "./source-scope.ts";
+import { StateError } from "../state/types.ts";
+import { kpiSource } from "../source/kpi.ts";
+import { sourceComponentClass } from "../render/components.ts";
+import type { KpiAppearance } from "../render/kpi.ts";
+import type { BentoDoc, Element } from "../render/types.ts";
+export type KpiAppearances = ReadonlyMap<string, KpiAppearance>;
+/** A globally identified source wrapper must have exactly one native receipt. */
+function sourceBackedScope(
+  state: ProjectState,
+  source: SourceDocument,
+  sourceSlideId: string,
+  componentId: string,
+): string | undefined {
+  const backgroundId = `${componentId}/qb-kpi-background`;
+  const groupId = kpiSource(source, componentId).groupId;
+  const candidates = Object.entries(state.provenance).flatMap(
+    ([key, proof]) => {
+      let target: unknown;
+      try {
+        target = JSON.parse(key);
+      } catch {
+        return [];
+      }
+      if (
+        !Array.isArray(target) || target.length !== 2 ||
+        typeof target[0] !== "string" || !target[0] ||
+        target[1] !== backgroundId ||
+        proof.origin !== "authored" || proof.semanticId !== componentId ||
+        proof.source?.kind !== "div" || proof.source.blockId !== componentId ||
+        proof.source.stable !== true
+      ) return [];
+      const baseline = state.generatedBaseline.slides.find((slide) =>
+        slide.id === target[0]
+      )
+        ?.elements.find((element) => element.id === backgroundId);
+      return baseline?.type === "shape" && baseline.shape === "rect" &&
+          baseline.groupId === groupId
+        ? [target[0]]
+        : [];
+    },
+  );
+  if (candidates.length !== 1) return;
+  try {
+    const slideId = verifiedSourceSlide(
+      source,
+      state,
+      sourceSlideId,
+      candidates[0],
+    );
+    // A weak heading's receipt is valid only for this exact execution snapshot.
+    const heading = source.slides.find((slide) => slide.id === sourceSlideId)!;
+    if (
+      !heading.stable &&
+      state.provenance[targetKey({ slideId, elementId: backgroundId })].source
+          ?.hash !== source.hash
+    ) return;
+    return slideId;
+  } catch (error) {
+    if (error instanceof StateError && error.code === "UNMAPPED_SOURCE_SLIDE") {
+      return;
+    }
+    throw error;
+  }
+}
+export function retainedKpiAppearances(
+  state: ProjectState | null | undefined,
+  source: SourceDocument,
+): KpiAppearances {
+  const appearances = new Map<string, KpiAppearance>();
+  if (!state) return appearances;
+  for (
+    const block of source.blocks.filter((block) =>
+      block.kind === "div" && block.stable &&
+      sourceComponentClass(block.raw) === ".bento-kpi"
+    )
+  ) {
+    const binding = kpiSource(source, block.id), sourceSlideId = block.slideId;
+    if (!sourceSlideId) continue;
+    // Pending roles have explicit membership; source-backed roles require the
+    // unique original background receipt before any native slide is considered.
+    const intent = state.componentCreations?.find((intent) =>
+      intent.kind === "kpi" && intent.id === block.id
+    );
+    let slideId: string | undefined;
+    if (intent) {
+      try {
+        slideId = verifiedSourceSlide(
+          source,
+          state,
+          sourceSlideId,
+          intent.slideId,
+        );
+      } catch (error) {
+        if (
+          !(error instanceof StateError) ||
+          error.code !== "UNMAPPED_SOURCE_SLIDE"
+        ) throw error;
+      }
+    } else {
+      slideId = sourceBackedScope(state, source, sourceSlideId, block.id);
+    }
+    if (!slideId) continue;
+    const elements = new Map<string, Element>();
+    const backgroundId = `${block.id}/qb-kpi-background`;
+    const backgroundProof =
+      state.provenance[targetKey({ slideId, elementId: backgroundId })];
+    const baselineBackground = state.generatedBaseline.slides.find((slide) =>
+      slide.id === slideId
+    )
+      ?.elements.find((element) => element.id === backgroundId);
+    const sourceBacked = backgroundProof?.origin === "authored" &&
+      backgroundProof.semanticId === block.id &&
+      backgroundProof.source?.kind === "div" &&
+      backgroundProof.source?.blockId === block.id &&
+      baselineBackground?.type === "shape" &&
+      baselineBackground.shape === "rect" &&
+      baselineBackground.groupId === binding.groupId;
+    for (const slot of binding.slots) {
+      const nativeId = slot.paragraph.id;
+      const member = intent?.members.find((member) =>
+        member.nativeId === nativeId &&
+        member.sourceId === slot.wrapper.id &&
+        member.role === slot.role
+      );
+      if (member) {
+        elements.set(nativeId, clone(member.snapshot));
+        continue;
+      }
+      if (!sourceBacked) continue;
+      const proof =
+        state.provenance[targetKey({ slideId, elementId: nativeId })];
+      const current = state.emitted.slides.find((slide) => slide.id === slideId)
+        ?.elements.find((element) => element.id === nativeId);
+      if (
+        current?.type === "text" &&
+        !!proof && ["authored", "computed"].includes(proof.origin) &&
+        proof.semanticId === nativeId && proof.source?.kind === "paragraph" &&
+        proof.source?.blockId === nativeId &&
+        proof.source?.parentId === slot.wrapper.id &&
+        proof.source?.siblings === 1 &&
+        proof.source?.hash === backgroundProof.source?.hash
+      ) {
+        elements.set(nativeId, clone(current));
+      }
+    }
+    if (elements.size) {
+      const previous = appearances.get(slideId);
+      const combined = new Map(previous?.elements ?? []);
+      for (const [id, element] of elements) combined.set(id, element);
+      appearances.set(slideId, {
+        elements: combined,
+        resources: state.emitted as unknown as BentoDoc,
+      });
+    }
+  }
+  return appearances;
+}
+/** Rescue keeps the actual saved boxes as visual overlays, not source baseline fields. */
+export function preserveRescuedKpiGeometry(
+  state: ProjectState,
+  appearances: KpiAppearances,
+  rescues: { slideId: string; elementIds: string[] }[],
+  ownership: ProjectState["ownership"],
+): void {
+  for (const rescue of rescues) {
+    for (const elementId of rescue.elementIds) {
+      const native = appearances.get(rescue.slideId)?.elements.get(elementId);
+      const current = state.emitted.slides.find((slide) =>
+        slide.id === rescue.slideId
+      )
+        ?.elements.find((element) => element.id === elementId);
+      if (!native || current?.type !== "text") continue;
+      const target = { slideId: rescue.slideId, elementId },
+        key = targetKey(target);
+      for (const field of ["x", "y", "w", "h"]) {
+        if (
+          typeof native[field] !== "number" || !Number.isFinite(native[field])
+        ) continue;
+        if (
+          ownership[key]?.some((path) =>
+            path === field || field.startsWith(path + "/")
+          )
+        ) continue;
+        let overlay = state.overrides.find((overlay) =>
+          targetKey(overlay.target) === key
+        );
+        if (!overlay) {
+          overlay = { target, fields: [] };
+          state.overrides.push(overlay);
+        }
+        overlay.fields = overlay.fields.filter((item) =>
+          item.path.length !== 1 || item.path[0] !== field
+        );
+        overlay.fields.push({
+          path: [field],
+          value: { present: true, value: native[field] },
+        });
+      }
+    }
+  }
+}

package/distribution/runtime/src/core/layouts.ts

@@ -0,0 +1,245 @@
+/** Explicit, design-only application of reusable layout definitions to saved objects. */
+import { withProject } from "./project.ts";
+import { hashSource, scanSource } from "../source/mod.ts";
+import { builtinLayouts, type Frame } from "../render/design.ts";
+import {
+  assertDesignRegistryUnchanged,
+  readDesignRegistry,
+} from "../render/registry.ts";
+import { nativeLayoutFrame } from "../render/native-layout.ts";
+import { assertProjectDocument } from "../render/validate.ts";
+import {
+  assertOutputUnchanged,
+  captureEdits,
+  equal,
+  type ProjectState,
+  StateError,
+  targetKey,
+} from "../state/mod.ts";
+export interface LayoutRequest {
+  expectedDocId: string;
+  expectedRevision: number;
+  expectedSourceHash: string;
+  expectedRegistryHash: string | null;
+  slideId: string;
+  layout: string;
+  /** Ordered explicit native IDs per column; no automatic membership matching. */
+  columns: string[][];
+}
+function fail(code: string, message: string): never {
+  throw new StateError(code, message);
+}
+function requestShape(request: LayoutRequest) {
+  if (
+    !request || typeof request !== "object" || Array.isArray(request) ||
+    Object.keys(request).sort().join(",") !==
+      "columns,expectedDocId,expectedRegistryHash,expectedRevision,expectedSourceHash,layout,slideId" ||
+    typeof request.expectedDocId !== "string" || !request.expectedDocId ||
+    !Number.isSafeInteger(request.expectedRevision) ||
+    request.expectedRevision < 0 ||
+    typeof request.expectedSourceHash !== "string" ||
+    !/^[a-f0-9]{64}$/.test(request.expectedSourceHash) ||
+    !(request.expectedRegistryHash === null ||
+      typeof request.expectedRegistryHash === "string" &&
+        /^[a-f0-9]{64}$/.test(request.expectedRegistryHash)) ||
+    typeof request.slideId !== "string" || !request.slideId ||
+    typeof request.layout !== "string" ||
+    !Array.isArray(request.columns) || request.columns.length < 1 ||
+    request.columns.length > 6 ||
+    request.columns.some((ids) =>
+      !Array.isArray(ids) || !ids.length || ids.length > 200 ||
+      ids.some((id) => typeof id !== "string" || !id)
+    )
+  ) {
+    fail(
+      "INVALID_LAYOUT_REQUEST",
+      "Select a saved slide, layout and explicit objects for every column.",
+    );
+  }
+}
+function catalog(
+  state: ProjectState,
+  text: string,
+  registry: Awaited<ReturnType<typeof readDesignRegistry>>,
+) {
+  const source = scanSource(text),
+    headings = new Set(source.slides.map((slide) => slide.headingId));
+  // Weak source IDs include offsets. A newer source cannot safely classify the
+  // saved objects (especially slide titles) before a fresh projection.
+  if (
+    Object.values(state.provenance).some((proof) =>
+      typeof proof.source?.hash === "string" &&
+      proof.source.hash !== source.hash
+    )
+  ) {
+    fail(
+      "STALE_SOURCE",
+      "QMD changed since the saved projection. Recalculate before applying a layout; saved and pending edits remain recoverable.",
+    );
+  }
+  const size = state.emitted.size as { width: number; height: number };
+  // Existing projected title region is reserved. Explicitly moved source titles
+  // can increase it, but are never moved or selected by this action.
+  const slides = state.emitted.slides.map((slide) => {
+    const titles = slide.elements.filter((element) =>
+      element.role === "title" ||
+      headings.has(
+        String(
+          state
+            .provenance[targetKey({ slideId: slide.id, elementId: element.id })]
+            ?.semanticId,
+        ),
+      )
+    );
+    const top = Math.max(
+      size.height * 166 / 720,
+      ...titles.map((e) => Number(e.y) + Number(e.h) + 24),
+    );
+    const frame: Frame = {
+      x: size.width / 16,
+      y: top,
+      w: size.width * 7 / 8,
+      h: size.height - top - size.height * 84 / 720,
+    };
+    return {
+      id: slide.id,
+      label: String(slide.title ?? slide.id),
+      frame,
+      elements: slide.elements.filter((e) =>
+        !titles.includes(e) &&
+        ["text", "code", "image", "table", "chart"].includes(e.type)
+      ).map((element) => ({
+        id: element.id,
+        type: element.type,
+        label: String(
+          element.html ?? element.content ?? element.alt ?? element.id,
+        ).replace(/<[^>]*>/g, "").slice(0, 120),
+      })),
+    };
+  });
+  return {
+    docId: state.docId,
+    revision: state.revision,
+    sourceHash: source.hash,
+    registryHash: registry.hash,
+    layouts: { ...builtinLayouts, ...registry.registry.layouts },
+    slides,
+  };
+}
+export async function readLayouts(source: string) {
+  return await withProject(source, async (paths, store) => {
+    const state = await store.load();
+    if (!state) fail("NO_BASELINE", "Render the project first.");
+    return catalog(
+      state,
+      await Deno.readTextFile(paths.source),
+      await readDesignRegistry(paths.directory),
+    );
+  });
+}
+async function operation(
+  source: string,
+  request: LayoutRequest,
+  save: boolean,
+) {
+  requestShape(request);
+  return await withProject(source, async (paths, store) => {
+    const state = await store.load();
+    if (!state) fail("NO_BASELINE", "Render the project first.");
+    if (state.docId !== request.expectedDocId) {
+      fail("DOC_ID_CHANGED", "Reload the project before applying a layout.");
+    }
+    if (state.revision !== request.expectedRevision) {
+      fail("STALE_REVISION", "Saved objects changed; reopen Apply layout.");
+    }
+    const text = await Deno.readTextFile(paths.source);
+    if (hashSource(text) !== request.expectedSourceHash) {
+      fail("STALE_SOURCE", "QMD changed; reopen Apply layout.");
+    }
+    const registry = await readDesignRegistry(paths.directory);
+    if (registry.hash !== request.expectedRegistryHash) {
+      fail(
+        "DESIGN_REGISTRY_CHANGED",
+        "Layout definitions changed; reopen Apply layout.",
+      );
+    }
+    const choices = catalog(state, text, registry),
+      slide = choices.slides.find((s) => s.id === request.slideId);
+    if (!slide) fail("LAYOUT_SLIDE_SCOPE", "Choose an existing saved slide.");
+    if (!Object.hasOwn(choices.layouts, request.layout)) {
+      fail("UNKNOWN_LAYOUT", "Choose a declared layout.");
+    }
+    const layout = choices.layouts[request.layout];
+    if (request.columns.length !== layout.columns) {
+      fail(
+        "LAYOUT_COLUMN_COUNT",
+        "Assign objects explicitly to every column of this layout.",
+      );
+    }
+    const ids = request.columns.flat();
+    if (
+      new Set(ids).size !== ids.length ||
+      ids.some((id) => !slide.elements.some((e) => e.id === id))
+    ) {
+      fail(
+        "LAYOUT_ELEMENT_SCOPE",
+        "Every selected object must occur once on this slide; titles stay outside the content layout.",
+      );
+    }
+    const width =
+      (slide.frame.w - 2 * layout.padding - (layout.columns - 1) * layout.gap) /
+      layout.columns;
+    const height = slide.frame.h - 2 * layout.padding;
+    const doc = structuredClone(state.emitted),
+      native = doc.slides.find((s) => s.id === slide.id)!;
+    const placements = request.columns.flatMap((members, column) => {
+      const h = (height - (members.length - 1) * layout.gap) / members.length;
+      if (width <= 0 || h <= 0) {
+        fail(
+          "LAYOUT_CONTENT_OVERFLOW",
+          "The selected layout has no usable content area.",
+        );
+      }
+      return members.map((id, row) => {
+        const element = native.elements.find((e) => e.id === id)!;
+        const frame = nativeLayoutFrame(element, {
+          x: slide.frame.x + layout.padding + column * (width + layout.gap),
+          y: slide.frame.y + layout.padding + row * (h + layout.gap),
+          w: width,
+          h,
+        });
+        Object.assign(element, frame);
+        return { id, ...frame };
+      });
+    });
+    assertProjectDocument(doc);
+    const next = equal(doc, state.emitted) ? state : captureEdits(state, doc);
+    const preview = {
+      ...choices,
+      slideId: slide.id,
+      layout: request.layout,
+      placements,
+      pending: next.pending.length,
+    };
+    // Recheck all external authorities after adaptation and before the single
+    // state write. Generated HTML is never replaced by this action.
+    await assertOutputUnchanged(state, paths.output);
+    if (
+      hashSource(await Deno.readTextFile(paths.source)) !==
+        request.expectedSourceHash
+    ) fail("STALE_SOURCE", "QMD changed while preparing layout.");
+    await assertDesignRegistryUnchanged(
+      paths.directory,
+      request.expectedRegistryHash,
+    );
+    if (!save) return preview;
+    const saved = next === state ? state : await store.save(next);
+    return { ...preview, revision: saved.revision };
+  });
+}
+export async function previewLayout(source: string, request: LayoutRequest) {
+  return await operation(source, request, false);
+}
+export async function applyLayout(source: string, request: LayoutRequest) {
+  return await operation(source, request, true);
+}