@ryanyahya/opendoc 0.4.0

package/src/server/media-mutations.ts

@@ -0,0 +1,168 @@
+import { constants, lstatSync, mkdirSync, openSync, closeSync, fstatSync, readFileSync, renameSync, realpathSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { prepareMediaImage, type UploadFile } from '../assets/imports';
+import { hashBytes, mediaId, parseMediaMeta } from '../media/files';
+import type { MediaKind, MediaMeta } from '../shared/media';
+import { Conflict, withCommentLock } from './comments';
+import { documentEntry } from './render';
+
+export interface MediaImportMetadata {
+  id?: string;
+  title: string;
+  description: string;
+  kind: MediaKind;
+  alt?: string;
+  attribution?: string;
+  sources?: string[];
+}
+export interface MediaMutationResult { documentId: string; id: string; metadataRevision: string }
+const editable = ['title', 'description', 'kind', 'alt', 'attribution', 'sources'] as const;
+const known = [...editable, 'file', 'data', 'recipe'];
+const metadataHash = (meta: unknown) => hashBytes(Buffer.from(JSON.stringify(meta)));
+
+/** Check each component before creating the next one; never follow a linked folder. */
+function ordinaryDirectory(root: string, parts: string[], create = false) {
+  let path = root;
+  for (const part of parts) {
+    path = resolve(path, part);
+    let info;
+    try { info = lstatSync(path); }
+    catch (error) {
+      if (!create || (error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      try { mkdirSync(path); } catch (failure) { if ((failure as NodeJS.ErrnoException).code !== 'EEXIST') throw failure; }
+      info = lstatSync(path);
+    }
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Document media must stay in ordinary local folders, without symbolic links.');
+  }
+  return path;
+}
+
+async function ownerDirectory(root: string, documentId: string) {
+  const entry = await documentEntry(root, documentId);
+  const directory = ordinaryDirectory(root, ['documents', documentId]);
+  const info = lstatSync(resolve(directory, 'index.tsx'));
+  if (!info.isFile() || info.isSymbolicLink() || entry !== resolve(directory, 'index.tsx')) throw new Error('Choose an ordinary document in this workspace as the media owner.');
+  return directory;
+}
+
+function readMetadata(folder: string) {
+  const file = resolve(folder, 'meta.json');
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile() || info.size > 32_000) throw new Error('Keep media metadata in a regular local file below 32 KB.');
+    const value = JSON.parse(readFileSync(fd, 'utf8')) as unknown;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('meta.json must contain a media record.');
+    const raw = value as Record<string, unknown>;
+    // Preserve future or source-specific fields without giving this editor authority to change them.
+    parseMediaMeta(Object.fromEntries(Object.entries(raw).filter(([key]) => known.includes(key as (typeof known)[number]))));
+    return raw;
+  } finally { closeSync(fd); }
+}
+
+function metadataText(meta: unknown) {
+  const text = JSON.stringify(meta, null, 2) + '\n';
+  if (Buffer.byteLength(text) > 32_000) throw new Error('Keep media metadata below 32 KB.');
+  return text;
+}
+
+function stagingRoot(root: string) {
+  const directory = ordinaryDirectory(root, ['.opendoc', 'media-imports'], true);
+  // A killed import can leave its private stage behind. Only remove dead-process stages
+  // with the exact files this service owns; leave any unexpected user material alone.
+  for (const name of readdirSync(directory)) {
+    const match = /^(\d+)-[0-9a-f-]{36}$/.exec(name);
+    if (!match) continue;
+    try {
+      const path = resolve(directory, name);
+      const info = lstatSync(path);
+      if (!info.isDirectory() || info.isSymbolicLink()) continue;
+      try { process.kill(Number(match[1]), 0); continue; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') continue; }
+      const entries = readdirSync(path, { withFileTypes: true });
+      if (entries.every(entry => entry.isFile() && ['image.png', 'image.jpg', 'meta.json'].includes(entry.name))) rmSync(path, { recursive: true, force: true });
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  }
+  return directory;
+}
+
+function prepareDocumentLock(root: string, documentId: string) {
+  const directory = ordinaryDirectory(root, ['.opendoc', 'locks'], true);
+  try {
+    const info = lstatSync(resolve(directory, `${documentId}.lock`));
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('The document lock must be an ordinary local folder, without symbolic links.');
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+}
+
+export async function importMedia(root: string, documentId: string, metadata: MediaImportMetadata, file: UploadFile): Promise<MediaMutationResult> {
+  const workspace = realpathSync(root);
+  await ownerDirectory(workspace, documentId);
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) throw new Error('Give the image a title, description, and kind.');
+  for (const key of Object.keys(metadata)) if (key !== 'id' && !editable.includes(key as (typeof editable)[number])) throw new Error(`This image import cannot set ${key}. Add preparation files separately.`);
+  if (metadata.id !== undefined && (!mediaId.test(metadata.id) || metadata.id.length > 100)) throw new Error('Use a lowercase media ID with single hyphens, up to 100 characters.');
+  const { id: requestedId, ...fields } = metadata;
+  // Validate text before starting the bounded image parser.
+  parseMediaMeta({ ...fields, file: 'image.png' });
+  const image = await prepareMediaImage(file);
+  const name = image.mime === 'image/png' ? 'image.png' : 'image.jpg';
+  const meta = parseMediaMeta({ ...fields, file: name });
+  const text = metadataText(meta);
+  const stageRoot = stagingRoot(workspace);
+  prepareDocumentLock(workspace, documentId);
+  const stage = resolve(stageRoot, `${process.pid}-${randomUUID()}`);
+  mkdirSync(stage);
+  try {
+    writeFileSync(resolve(stage, name), image.contents, { flag: 'wx' });
+    writeFileSync(resolve(stage, 'meta.json'), text, { flag: 'wx' });
+    return await withCommentLock(workspace, documentId, async () => {
+      await ownerDirectory(workspace, documentId);
+      const parent = ordinaryDirectory(workspace, ['documents', documentId, 'media'], true);
+      let id = requestedId ?? (metadata.title.normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80).replace(/-$/, '') || 'media');
+      let target = resolve(parent, id);
+      try {
+        lstatSync(target);
+        if (requestedId) throw new Conflict('That media ID already exists. Choose another ID; the existing visual was preserved.');
+        id = `${id}-${randomUUID().slice(0, 8)}`; target = resolve(parent, id);
+        try { lstatSync(target); throw new Conflict('That media ID already exists. Try adding the image again.'); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      // No asynchronous gap between the final existence check and directory publication.
+      renameSync(stage, target);
+      return { documentId, id, metadataRevision: metadataHash(meta) };
+    });
+  } finally { rmSync(stage, { recursive: true, force: true }); }
+}
+
+export async function editMedia(root: string, documentId: string, id: string, input: { expectedRevision: string; meta: MediaMeta }): Promise<MediaMutationResult> {
+  const workspace = realpathSync(root);
+  await ownerDirectory(workspace, documentId);
+  if (!mediaId.test(id)) throw new Error('Choose a valid media item.');
+  if (!input || typeof input.expectedRevision !== 'string' || !/^[a-f0-9]{64}$/.test(input.expectedRevision)) throw new Conflict('Reload this image before saving its metadata.');
+  if (!input.meta || typeof input.meta !== 'object' || Array.isArray(input.meta)) throw new Error('Provide the image metadata to edit.');
+  prepareDocumentLock(workspace, documentId);
+  return withCommentLock(workspace, documentId, async () => {
+    await ownerDirectory(workspace, documentId);
+    const folder = ordinaryDirectory(workspace, ['documents', documentId, 'media', id]);
+    const current = readMetadata(folder);
+    if (metadataHash(current) !== input.expectedRevision) throw new Conflict('This image metadata changed. Reload it before saving; your changes have not overwritten it.');
+    for (const [key, value] of Object.entries(input.meta)) {
+      if (!editable.includes(key as (typeof editable)[number]) && JSON.stringify(value) !== JSON.stringify(current[key])) throw new Error(`The metadata editor cannot change ${key}. Ask your agent to update preparation files separately.`);
+    }
+    const next = { ...current };
+    for (const key of editable) {
+      if (input.meta[key] === undefined) delete next[key];
+      else next[key] = input.meta[key];
+    }
+    parseMediaMeta(Object.fromEntries(Object.entries(next).filter(([key]) => known.includes(key as (typeof known)[number]))));
+    const text = metadataText(next);
+    const temporary = resolve(folder, `.meta-${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temporary, text, { flag: 'wx' });
+      ordinaryDirectory(workspace, ['documents', documentId, 'media', id]);
+      if (metadataHash(readMetadata(folder)) !== input.expectedRevision) throw new Conflict('This image metadata changed while saving. Reload it and try again.');
+      renameSync(temporary, resolve(folder, 'meta.json'));
+    } finally { try { unlinkSync(temporary); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; } }
+    return { documentId, id, metadataRevision: metadataHash(next) };
+  });
+}

package/src/server/pptx.ts

@@ -0,0 +1,160 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import * as fontkit from 'fontkit';
+import ttf2eot from 'ttf2eot';
+import TsPptx, { type TextPropsOptions } from '@shbernal/ts-pptx';
+import type { ElementInfo, ElementStyleInfo, LayoutInfo, Color } from '@formepdf/core';
+import type { FormeDocument, FormeNode, FormeStyle } from '@formepdf/react';
+import type { DocumentMeta, SlideInfo, SourceLocation } from '../shared/types';
+
+export interface PresentationCapture {
+  version: 1; hash: string; meta: DocumentMeta; slides: SlideInfo[]; doc: FormeDocument; layout: LayoutInfo;
+}
+type TextKind = Extract<FormeNode['kind'], { type: 'Text' | 'Heading' }>;
+type Run = { text: string; style: FormeStyle; href?: string };
+type FontFace = { bytes: Buffer; family: string; weight: number; italic: boolean; restrictions: { noEmbedding?: boolean; bitmapOnly?: boolean; viewOnly?: boolean } };
+type PaintStyle = ElementStyleInfo & { borderStyle?: Partial<Record<'top' | 'right' | 'bottom' | 'left', string>>; transform?: unknown };
+const PT = 72;
+const key = (location: SourceLocation | undefined, type: string) => `${location?.file ?? ''}:${location?.line ?? 0}:${location?.column ?? 0}:${type}`;
+const hex = (color: Color) => [color.r, color.g, color.b].map(v => Math.round(v * 255).toString(16).padStart(2, '0')).join('').toUpperCase();
+const fill = (color: Color) => ({ color: hex(color), transparency: (1 - (color.a ?? 1)) * 100 });
+const box = (node: ElementInfo) => ({ x: node.x / PT, y: node.y / PT, w: node.width / PT, h: node.height / PT });
+
+/** Preserve authored runs inside one editable textbox, using the reviewed line breaks. */
+export function presentationTextRuns(source: TextKind, lines: Pick<ElementInfo, 'textContent'>[]): Run[] | null {
+  const input = source.runs ?? [{ content: source.content, href: source.href }];
+  if (input.map(r => r.content).join('').replace(/\s/g, '') !== lines.map(l => l.textContent ?? '').join('').replace(/\s/g, '')) return null;
+  const chars = input.flatMap(run => Array.from(run.content, c => ({ c, style: run.style ?? {}, href: run.href ?? source.href })));
+  let position = 0;
+  const output: Run[] = [];
+  for (const [index, line] of lines.entries()) {
+    if (index) output.push({ text: '\n', style: {} });
+    for (const c of line.textContent ?? '') {
+      while (position < chars.length && /\s/.test(chars[position].c) && chars[position].c !== c) position++;
+      if (position >= chars.length || chars[position].c !== c) return null;
+      const run = chars[position++], last = output.at(-1);
+      if (last && last.text !== '\n' && JSON.stringify(last.style) === JSON.stringify(run.style) && last.href === run.href) last.text += c;
+      else output.push({ text: c, style: run.style, href: run.href });
+    }
+    while (position < chars.length && /\s/.test(chars[position].c)) position++;
+  }
+  return output;
+}
+
+function fontCatalog(doc: FormeDocument) {
+  const fonts = new Map<string, FontFace>();
+  for (const item of doc.fonts ?? []) {
+    const bytes = typeof item.src === 'string' ? Buffer.from(item.src, 'base64') : Buffer.from(item.src);
+    const font = fontkit.create(bytes);
+    if (!('familyName' in font)) throw new Error('PowerPoint export requires individual font faces, not a font collection.');
+    const restrictions = (font as unknown as { 'OS/2'?: { fsType?: FontFace['restrictions'] } })['OS/2']?.fsType ?? {};
+    fonts.set(`${item.family}:${item.weight ?? 400}:${!!item.italic}`, { bytes, family: font.familyName, weight: item.weight ?? 400, italic: !!item.italic, restrictions });
+  }
+  return fonts;
+}
+
+export async function presentationBytes(capture: PresentationCapture): Promise<Uint8Array> {
+  if (capture.version !== 1 || capture.slides.length !== capture.layout.pages.length || capture.doc.children.length !== capture.slides.length) throw new Error('The presentation preview is incomplete. Render it again before exporting.');
+  const fonts = fontCatalog(capture.doc), used = new Map<string, FontFace>();
+  const pptx = new TsPptx();
+  pptx.defineLayout({ name: 'OPENDOC', width: 960 / PT, height: 540 / PT });
+  pptx.layout = 'OPENDOC'; pptx.title = capture.meta.title; pptx.author = capture.meta.author ?? 'OpenDoc';
+  function textStyle(style: ElementStyleInfo): TextPropsOptions {
+    // Match Forme 0.20.1 FontRegistry::resolve: exact, snapped, then opposite weight.
+    // Choosing the numerically closest face would disagree with the reviewed PDF.
+    const weight = style.fontWeight ?? 400, snapped = weight >= 600 ? 700 : 400;
+    let font: FontFace | undefined;
+    for (const family of style.fontFamily.split(',').map(name => name.trim().replace(/^["']|["']$/g, ''))) {
+      for (const candidate of [weight, snapped, snapped === 700 ? 400 : 700]) {
+        font = fonts.get(`${family}:${candidate}:${style.fontStyle === 'Italic'}`);
+        if (font) break;
+      }
+      if (font) break;
+    }
+    if (!font) throw new Error(`PowerPoint export needs the exact font face: ${style.fontFamily}, weight ${style.fontWeight}.`);
+    const slot = `${font.family}:${font.weight >= 600}:${font.italic}`, previous = used.get(slot);
+    if (previous && !previous.bytes.equals(font.bytes)) throw new Error(`PowerPoint cannot preserve these different weights of ${font.family} in the same font style. Use regular and semibold/bold faces.`);
+    used.set(slot, font);
+    return { fontFace: font.family, fontSize: style.fontSize, bold: font.weight >= 600, italic: font.italic,
+      color: hex(style.color), transparency: (1 - (style.color.a ?? 1)) * 100, charSpacing: style.letterSpacing ?? 0,
+      ...(style.textDecoration === 'Underline' ? { underline: { style: 'sng' as const } } : {}), ...(style.textDecoration === 'LineThrough' ? { strike: true } : {}) };
+  }
+  for (const [index, page] of capture.layout.pages.entries()) {
+    const sourcePage = capture.doc.children[index], label = capture.slides[index].id;
+    if (page.width !== 960 || page.height !== 540 || sourcePage.kind.type !== 'Page') throw new Error('PowerPoint export requires 960 × 540 presentation slides.');
+    const sources = new Map<string, FormeNode[]>();
+    function indexSource(node: FormeNode) {
+      const styles = [node.style, ...('runs' in node.kind ? node.kind.runs?.map(run => run.style) ?? [] : [])];
+      for (const style of styles) {
+        if (!style) continue;
+        const unsupported = style.transform?.length ? 'transforms' : style.boxShadow ? 'shadows' : style.background && style.background.type !== 'color' ? 'gradients' : style.wordSpacing ? 'custom word spacing' : style.textAlign === 'Justify' ? 'justified text' : undefined;
+        if (unsupported) throw new Error(`Slide ${label}: PowerPoint export does not yet support ${unsupported}.`);
+      }
+      if (['Text', 'Heading', 'Image'].includes(node.kind.type)) {
+        const id = key(node.sourceLocation, node.kind.type), list = sources.get(id) ?? [];
+        list.push(node); sources.set(id, list);
+      }
+      node.children.forEach(indexSource);
+    }
+    indexSource(sourcePage);
+    const slide = pptx.addSlide(), config = sourcePage.kind.config;
+    if (config.backgroundImage) slide.addImage({ data: config.backgroundImage, x: 0, y: 0, w: 960 / PT, h: 540 / PT, transparency: (1 - (config.backgroundOpacity ?? 1)) * 100 });
+    function visit(node: ElementInfo) {
+      const style = node.style as PaintStyle;
+      if (style.opacity === 0) return;
+      if (style.opacity !== undefined && style.opacity !== 1) throw new Error(`Slide ${label}: PowerPoint export does not yet support group opacity.`);
+      if (style.transform) throw new Error(`Slide ${label}: PowerPoint export does not yet support transforms.`);
+      if (node.kind === 'Rect') {
+        if (Object.values(style.borderRadius ?? {}).some(radius => radius !== 0)) throw new Error(`Slide ${label}: PowerPoint export does not yet support rounded corners.`);
+        if (style.backgroundColor) slide.addShape('rect', { ...box(node), line: { transparency: 100 }, fill: fill(style.backgroundColor) });
+        for (const side of ['top', 'right', 'bottom', 'left'] as const) if (style.borderWidth?.[side] > 0) {
+          if (style.borderStyle?.[side] !== 'solid') throw new Error(`Slide ${label}: PowerPoint export does not yet support this border style.`);
+          const horizontal = side === 'top' || side === 'bottom';
+          slide.addShape('line', { x: (node.x + (side === 'right' ? node.width : 0)) / PT, y: (node.y + (side === 'bottom' ? node.height : 0)) / PT,
+            w: horizontal ? node.width / PT : 0, h: horizontal ? 0 : node.height / PT,
+            line: { ...fill(style.borderColor[side]), width: style.borderWidth[side], beginArrowType: 'none', endArrowType: 'none' } });
+        }
+      }
+      const type = /^H[1-6]$/.test(node.nodeType) ? 'Heading' : node.nodeType;
+      if (['Text', 'Heading'].includes(type) && node.children.some(child => child.nodeType === 'TextLine')) {
+        const source = sources.get(key(node.sourceLocation, type))?.shift();
+        if (!source || (source.kind.type !== 'Text' && source.kind.type !== 'Heading')) throw new Error(`Slide ${label}: an editable text source could not be matched.`);
+        const lines = node.children.filter(child => child.nodeType === 'TextLine');
+        const pageNumbers = (text: string) => text.replaceAll('{{pageNumber}}', String(index + 1)).replaceAll('{{totalPages}}', String(capture.slides.length)).replaceAll('\u0002', String(index + 1)).replaceAll('\u0003', String(capture.slides.length));
+        const runs = presentationTextRuns({ ...source.kind, content: pageNumbers(source.kind.content), runs: source.kind.runs?.map(run => ({ ...run, content: pageNumbers(run.content) })) }, lines.map(line => ({ textContent: pageNumbers(line.textContent ?? '') })));
+        if (!runs) throw new Error(`Slide ${label}: PowerPoint export cannot preserve this text transformation.`);
+        const rich = runs.map(run => ({ text: run.text, options: { ...textStyle({ ...style, ...run.style } as ElementStyleInfo), ...(run.href ? { hyperlink: { url: run.href } } : {}) } }));
+        slide.addText(rich, { ...box(node), y: lines[0].y / PT, ...textStyle(style), margin: 0, breakLine: false, paraSpaceAfter: 0, paraSpaceBefore: 0,
+          lineSpacing: style.fontSize * style.lineHeight, align: style.textAlign.toLowerCase() as TextPropsOptions['align'], valign: 'top', wrap: false, fit: 'none',
+          objectName: node.sourceLocation?.file?.replace('opendoc:block:', '') ?? 'text' });
+        return;
+      }
+      if (node.kind === 'Image') {
+        const source = sources.get(key(node.sourceLocation, 'Image'))?.shift();
+        if (source?.kind.type !== 'Image' || !source.kind.src) throw new Error(`Slide ${label}: an image source could not be matched.`);
+        slide.addImage({ data: source.kind.src, ...box(node), altText: source.alt ?? '' }); return;
+      }
+      if (!['Rect', 'None', 'Text'].includes(node.kind)) throw new Error(`Slide ${label}: PowerPoint export does not yet support ${node.nodeType}.`);
+      if (node.nodeType === 'TextLine') throw new Error(`Slide ${label}: an editable text line could not be matched.`);
+      node.children.forEach(visit);
+    }
+    page.elements.forEach(visit);
+  }
+  for (const font of used.values()) {
+    if (font.restrictions.noEmbedding || font.restrictions.bitmapOnly || font.restrictions.viewOnly) throw new Error(`${font.family} does not permit editable font embedding. Choose a font that does before exporting PowerPoint.`);
+    if (font.bytes.readUInt32BE(0) !== 0x00010000) throw new Error(`PowerPoint export currently requires TrueType outlines: ${font.family}.`);
+    // PowerPoint consumes EOT containers in .fntdata, not the raw TTF accepted by ts-pptx.
+    await pptx.embedFont({ data: ttf2eot(font.bytes), typeface: font.family, style: font.italic ? (font.weight >= 600 ? 'boldItalic' : 'italic') : (font.weight >= 600 ? 'bold' : 'regular') });
+  }
+  const bytes = await pptx.write({ outputType: 'uint8array' });
+  if (!(bytes instanceof Uint8Array)) throw new Error('PowerPoint export returned an unexpected file format.');
+  return bytes;
+}
+
+export async function readPresentationBytes(directory: string, hash: string) {
+  const capture = JSON.parse(await readFile(resolve(directory, 'presentation.json'), 'utf8')) as PresentationCapture;
+  const pdf = await readFile(resolve(directory, 'document.pdf'));
+  if (capture.hash !== hash || createHash('sha256').update(pdf).digest('hex') !== hash) throw new Error('The presentation preview changed. Wait for the latest preview and try again.');
+  return presentationBytes(capture);
+}

package/src/server/preflight.ts

@@ -0,0 +1,129 @@
+import { RenderFailure } from './render-error';
+import type { ElementInfo, LayoutInfo } from '@formepdf/core';
+import type { BlockInfo, OutlineEntry, ReviewIssue, SlideInfo } from '../shared/types';
+
+/** Verify slide identity as well as page count; a shifted or duplicated page must fail. */
+export function assertSlideLayout(layout: LayoutInfo, slides: SlideInfo[], blocks: Record<string, BlockInfo>) {
+  if (layout.pages.length !== slides.length) {
+    const message = `Presentation layout failed: ${slides.length} slides produced ${layout.pages.length} pages. Content must fit on its own slide; shorten it or split it into explicit slides.`;
+    throw new RenderFailure(message, [{ code: 'slide-page-count', severity: 'error', message }]);
+  }
+  const ids = new Set(slides.map(slide => slide.id));
+  for (const [index, page] of layout.pages.entries()) {
+    const expected = slides[index].id;
+    const found = new Set<string>();
+    const paper = { x: 0, y: 0, width: page.width, height: page.height };
+    const visit = (node: ElementInfo, inherited?: string, clips: ElementInfo[] = []) => {
+      const id = blockIdOf(node, inherited);
+      if (id && ids.has(id)) found.add(id);
+      const owner = id && blocks[id]?.slideId;
+      if (owner && owner !== expected) {
+        const message = `Slide ${owner}: component ${id} moved onto slide ${expected}. Content must fit on its own slide.`;
+        throw new RenderFailure(message, [{ code: 'slide-content-moved', severity: 'error', message, page: index + 1, blockId: id }]);
+      }
+      // Native View backgrounds/borders are drawable rectangles too. Document
+      // preflight permits decorative bleed; a slide's bounded composition does not.
+      if (node.kind === 'Rect' && node.style.opacity !== 0 && (outside(node, paper) || clips.some(box => outside(node, box)))) {
+        const message = `Slide ${expected}: ${id ?? 'a visual'} extends outside the slide or is clipped. Resize or reposition it.`;
+        throw new RenderFailure(message, [{ code: 'slide-overflow', severity: 'error', message, page: index + 1, blockId: id }]);
+      }
+      const nextClips = node.style?.overflow === 'Hidden' ? [...clips, node] : clips;
+      node.children.forEach(child => visit(child, id, nextClips));
+    };
+    page.elements.forEach(node => visit(node));
+    if (page.width !== 960 || page.height !== 540 || found.size !== 1 || !found.has(expected)) {
+      const message = `Slide ${expected}: content moved to another page or the slide dimensions changed. Each slide must stay on its own 960 × 540 page.`;
+      throw new RenderFailure(message, [{ code: 'slide-identity', severity: 'error', message, page: index + 1, blockId: expected }]);
+    }
+  }
+}
+
+const tolerance = 0.75;
+const visualKinds = new Set(['Image', 'Svg', 'QrCode', 'Barcode', 'Canvas', 'BarChart', 'LineChart', 'PieChart', 'AreaChart', 'DotPlot']);
+type Mark = { node: ElementInfo; blockId?: string; heading?: ElementInfo; fixed: boolean };
+function blockIdOf(node: ElementInfo, inherited?: string) {
+  const source = node.sourceLocation?.file;
+  return source?.startsWith('opendoc:block:') ? source.slice(14) : inherited;
+}
+function overlaps(a: ElementInfo, b: ElementInfo) {
+  return a.x < b.x + b.width - tolerance && b.x < a.x + a.width - tolerance &&
+    a.y < b.y + b.height - tolerance && b.y < a.y + a.height - tolerance;
+}
+function outside(node: ElementInfo, box: { x: number; y: number; width: number; height: number }) {
+  return node.x < box.x - tolerance || node.y < box.y - tolerance ||
+    node.x + node.width > box.x + box.width + tolerance || node.y + node.height > box.y + box.height + tolerance;
+}
+
+/** Check concrete geometry, not aesthetic taste. Decorative page backgrounds may bleed. */
+export function inspectLayout(layout: LayoutInfo, blocks: Record<string, BlockInfo>) {
+  const issues: ReviewIssue[] = [];
+  const outline: OutlineEntry[] = [];
+  const seen = new Set<string>();
+  const outlined = new Set<string>();
+  const add = (issue: ReviewIssue) => {
+    const key = `${issue.code}:${issue.page}:${issue.blockId ?? ''}`;
+    if (!seen.has(key)) { seen.add(key); issues.push(issue); }
+  };
+  for (const [index, page] of layout.pages.entries()) {
+    const number = index + 1;
+    const leaves: Mark[] = [], headings: Mark[] = [];
+    const paper = { x: 0, y: 0, width: page.width, height: page.height };
+    const visit = (node: ElementInfo, inherited?: string, fixed = false, heading?: ElementInfo, clips: ElementInfo[] = []) => {
+      const blockId = blockIdOf(node, inherited);
+      fixed ||= node.nodeType === 'FixedHeader' || node.nodeType === 'FixedFooter';
+      if (/^H[1-6]$/.test(node.nodeType)) {
+        heading = node;
+        headings.push({ node, blockId, fixed });
+      }
+      const visible = node.nodeType === 'TextLine' ? !!node.textContent?.trim() : visualKinds.has(node.nodeType);
+      if (visible && node.style.opacity !== 0) {
+        leaves.push({ node, blockId, heading, fixed });
+        if (![node.x, node.y, node.width, node.height].every(Number.isFinite) || outside(node, paper)) {
+          add({ code: 'page-overflow', severity: 'error', page: number, blockId,
+            message: `Content extends beyond page ${number}. Reduce the fixed width or height, or allow the content to flow onto another page.` });
+        }
+        if (clips.some(box => outside(node, box))) {
+          add({ code: 'clipped-content', severity: 'error', page: number, blockId,
+            message: `Content is clipped by a fixed container on page ${number}. Remove the clipping or give it enough space.` });
+        }
+      }
+      const nextClips = node.style.overflow === 'Hidden' ? [...clips, node] : clips;
+      for (const child of node.children) visit(child, blockId, fixed, heading, nextClips);
+    };
+    for (const node of page.elements) visit(node);
+    const furniture = leaves.filter(mark => mark.fixed);
+    for (const mark of leaves) {
+      if (!mark.fixed && furniture.some(other => overlaps(mark.node, other.node))) {
+        add({ code: 'page-furniture-overlap', severity: 'error', page: number, blockId: mark.blockId,
+          message: `Content overlaps the running header or footer on page ${number}. Reduce the unbreakable content or adjust the page margins.` });
+      }
+    }
+    for (const mark of headings) {
+      if (mark.fixed) continue;
+      const heading = mark.node;
+      const title = leaves.filter(leaf => leaf.heading === heading).map(leaf => leaf.node.textContent ?? '').join(' ').trim();
+      if (mark.blockId && title && !outlined.has(mark.blockId)) {
+        outline.push({ id: mark.blockId, title, level: Number(heading.nodeType.slice(1)), page: number });
+        outlined.add(mark.blockId);
+      }
+      const lowerPage = heading.y + heading.height > page.contentY + page.contentHeight * 0.72;
+      const bodyFollows = leaves.some(leaf => !leaf.fixed && !leaf.heading && leaf.node.y >= heading.y + heading.height - tolerance &&
+        leaf.node.x < heading.x + heading.width && leaf.node.x + leaf.node.width > heading.x);
+      if (lowerPage && !bodyFollows) {
+        add({ code: 'stranded-heading', severity: 'warning', page: number, blockId: mark.blockId,
+          message: `“${title || blocks[mark.blockId ?? '']?.text || 'Heading'}” has no following body content on page ${number}. Use Section with a short lead to keep them together.` });
+      }
+    }
+    if (!leaves.some(mark => !mark.fixed)) {
+      add({ code: 'empty-page', severity: 'warning', page: number,
+        message: `Page ${number} has no body content. Check whether a page break or oversized block created an unwanted blank page.` });
+    }
+  }
+  return { issues, outline };
+}
+
+export function assertLayoutSafe(issues: ReviewIssue[]) {
+  const errors = issues.filter(issue => issue.severity === 'error');
+  if (!errors.length) return;
+  throw new RenderFailure(`Layout check failed:\n${errors.slice(0, 8).map(issue => `- ${issue.blockId ? `${issue.blockId}: ` : ''}${issue.message}`).join('\n')}${errors.length > 8 ? `\n- ${errors.length - 8} more layout errors.` : ''}`, issues);
+}

package/src/server/projects-cli.ts

@@ -0,0 +1,29 @@
+import { parseArgs } from 'node:util';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assignProject, createProject, deleteProject, readProjects, updateProject } from './projects';
+
+const usage = 'Usage: npx opendoc projects list [--json]\n       npx opendoc projects create <id> --name "Project name" [--theme <theme-id>]\n       npx opendoc projects update <id> [--name "Project name"] [--theme <theme-id|none>]\n       npx opendoc projects assign <document-id> <project-id>\n       npx opendoc projects delete <empty-project-id>';
+
+export async function runProjectsCli(args: string[], root = process.cwd()): Promise<void> {
+  const { values, positionals } = parseArgs({ args: args[0] === '--' ? args.slice(1) : args, allowPositionals: true, options: {
+    name: { type: 'string' }, theme: { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } });
+  const [action = 'list', id, projectId] = positionals;
+  let result: unknown;
+  if (values.help) {
+    console.log(values.json ? JSON.stringify({ usage }, null, 2) : usage);
+  } else {
+    if (action === 'list' && positionals.length <= 1) result = await readProjects(root);
+    else if (action === 'create' && id && positionals.length === 2) result = await createProject(root, { id, name: values.name, defaultTheme: values.theme === 'none' ? null : values.theme });
+    else if (action === 'update' && id && positionals.length === 2) result = await updateProject(root, id, { ...(values.name === undefined ? {} : { name: values.name }), ...(values.theme === undefined ? {} : { defaultTheme: values.theme === 'none' ? null : values.theme }) });
+    else if (action === 'assign' && id && projectId && positionals.length === 3) result = await assignProject(root, id, projectId);
+    else if (action === 'delete' && id && positionals.length === 2) { await deleteProject(root, id); result = { deleted: id }; }
+    else throw new Error('Unknown project command or missing arguments. Use npx opendoc projects --help.');
+    console.log(JSON.stringify(result, null, 2));
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  runProjectsCli(process.argv.slice(2)).catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+}