Resources panel: images, SVGs, HTML tables with captions, typed numbering & inline references

[drnachio]

Overview

The current ResourcesPanel is a placeholder ("Coming Soon"). This issue tracks the full design and implementation of a resources system covering:

1. An uploader / manager for bitmap images, SVGs, and HTML tables.
2. A built-in table editor supporting postext's markdown microformats, inline math, and col-span / row-span.
3. A per-resource caption that renders as the resource's figure/table foot in the viewer.
4. A configurable list of resource types (figure, table, diagram, image, …) managed separately, each with its own auto-numbering format and reset scope.
5. A markdown syntax extension so authors can reference resources inline, with numbers resolved automatically.

Automatic numbering follows order of first reference in the document, not creation order in the panel. Inserting a new reference earlier in the text renumbers the rest automatically.

1. Resource types — a separate concept

Location: new section in packages/postext-sandbox/src/sidebar/ConfigPanel.tsx, new config in packages/postext/src/types.ts

Resource types are a first-class, user-editable list. Each type defines:

interface ResourceType {
  id: string;                         // stable id, e.g. 'figure'
  name: string;                       // display name, e.g. "Figure"
  namePlural?: string;                // "Figures"
  shortLabel: string;                 // used in captions & references, e.g. "fig."

  // Numbering
  numberingTemplate: string;          // e.g. "{h1}.{n}" → "1.7", or "{n}" → "7"
  resetOn: 'never' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
  counterFormat: 'decimal' | 'roman-lower' | 'roman-upper' | 'alpha-lower' | 'alpha-upper';

  // Caption formatting
  captionPrefix: string;              // template, e.g. "{shortLabel} {number}. "  (produces "fig. 1.7. ")
}

The {h1}, {h2}, … tokens resolve to the current section number at the resource's first-reference point. The {n} token is the per-type counter.

Example: resetOn: 'h1', numberingTemplate: '{h1}.{n}' gives numbers like 1.1, 1.2, …, 2.1 — exactly the book convention the user described.

Each resource type keeps an independent counter: figures and tables don't interfere.

Built-in defaults provided out-of-the-box: figure, table. Users can add diagram, listing, equation, etc. from the settings UI.

2. Resource storage

Location: new packages/postext-sandbox/src/storage/resources.ts (IndexedDB), wired into the SandboxContext

type ResourceKind = 'bitmap' | 'svg' | 'table';

interface Resource {
  id: string;                 // slug-like, user-editable; must be unique
  typeId: string;             // references ResourceType.id
  kind: ResourceKind;
  caption?: string;           // rich text — parsed with the same inline microformats as body text
  altText?: string;           // accessibility; for bitmap/svg
  createdAt: number;
  updatedAt: number;

  // Kind-specific payload
  bitmap?: { fileId: string; format: 'png' | 'jpeg' | 'webp' | 'gif'; width: number; height: number; };
  svg?:    { fileId: string; };
  table?:  { model: TableModel; };
}

Binary blobs (bitmap / SVG source) live in IndexedDB, referenced by fileId — same pattern as custom fonts in #44. Tables are stored structurally (TableModel), not as raw HTML, to stay editable.

3. Table model & editor

Location: new packages/postext-sandbox/src/panels/resources/TableEditor/

interface TableCell {
  content: string;          // postext markdown microformat string
  colSpan?: number;         // default 1
  rowSpan?: number;         // default 1
  isHeader?: boolean;       // renders as <th>
  align?: 'left' | 'center' | 'right';
  verticalAlign?: 'top' | 'middle' | 'bottom';
}

interface TableModel {
  rows: TableCell[][];
  headerRowCount?: number;      // default 1
  // Optional style hooks to be expanded later (borders, zebra, column widths)
}

Cell content is parsed with the same inline microformat pipeline as body text:

• Bold **...**, italic *...*, code `...` — via inlineFormatting.ts
• Inline math $...$ — via inlineMath.ts
• Links and inline references (§5)

Reuse is mandatory, not optional. The editor calls the existing parsers so tables can't drift from body text semantics.

Editor UX must support:

• Add / remove rows and columns
• Merge cells (col-span + row-span) and un-merge
• Toggle header rows / header columns
• Per-cell alignment
• Keyboard navigation (Tab / Shift-Tab / arrow keys)
• Copy / paste of TSV / CSV for bulk data entry
• Undo / redo

4. Resources panel UI

Location: packages/postext-sandbox/src/sidebar/ResourcesPanel.tsx (currently a placeholder)

Replace the placeholder with a full manager:

• List of resources grouped by type, with thumbnails for bitmaps and a glyph for SVG / tables.
• "New" affordance with sub-options: Upload image, Upload SVG, New table.
• Per-resource detail pane: id (editable, auto-suggested from filename/caption), type selector, caption editor (uses the same inline microformat input as body text so **bold** / $x^2$ etc. work), alt text for a11y, and kind-specific controls (replace file for bitmap/svg, open the table editor for tables).
• Preview region showing exactly how the resource will render in the document, including the generated caption prefix (fig. 1.7. …) based on its type and a mock reference position.
• Delete with confirmation — the confirmation must warn if the resource is referenced anywhere in the markdown, listing the reference count.

5. Inline reference syntax — markdown extension

Location: packages/postext/src/parse/inlineFormatting.ts, packages/postext/src/parse/blockParser.ts

The markdown language must be extended so authors can reference resources inline. Two syntaxes:

5a. Block embed — places the resource at this point in the flow

::resource{id="lighthouse-diagram"}

On its own line, this directive embeds the resource here (caption included). This is what establishes the first-reference position for numbering purposes. If a resource is only ever ::resource-embedded once, its number is assigned at that embed point.

5b. Inline reference — cross-reference only, does not embed

As shown in :ref{id="lighthouse-diagram"}, the light is visible at 20 miles.

Renders inline as the formatted reference text — by default the resource type's shortLabel + number (e.g. fig. 1.7), but with options:

:ref{id="lighthouse-diagram"}                    → "fig. 1.7"
:ref{id="lighthouse-diagram" style="number"}     → "1.7"
:ref{id="lighthouse-diagram" style="full"}       → "Figure 1.7"
:ref{id="lighthouse-diagram" text="see it"}      → "see it"  (link text, number hidden)

An inline :ref before any ::resource embed counts as the first-reference position for numbering — this is what makes renumbering-on-insert work the way the user described. Embeds and references share the same numbering pass.

5c. Numbering pass

Location: new packages/postext/src/pipeline/resourceNumbering.ts

A new pipeline step, running after block parsing but before rendering:

1. Walk the parsed document in reading order.
2. For each resource id encountered (via either syntax), record the first occurrence.
3. For each resource type, assign counters in first-occurrence order, respecting the type's resetOn setting.
4. Produce a ResourceNumberingMap: Record<resourceId, { number: string; heading: HeadingContext; }>.
5. Pass the map to renderers so ::resource embeds get captions and :ref inlines get formatted numbers.

This mirrors the existing heading numbering pattern in packages/postext/src/numbering.ts — extend/parallel, don't duplicate.

6. Rendering

Location: packages/postext/src/canvas-backend/blockRender.ts, packages/postext-pdf/src/pdf-backend/index.ts

Canvas and PDF backends must gain:

• Bitmap block rendering (from IndexedDB blob → canvas image / PDF embedded image).
• SVG block rendering — rasterize for canvas preview, embed as vector in PDF.
• Table block rendering — lay out cells with col-span / row-span, measure via existing text measurement utilities, apply microformats and inline math inside cells.
• Caption rendering below the resource, prefixed per the resource type's captionPrefix template.
• Inline :ref rendered as a styled link (clickable in HTML, annotated in PDF) pointing at the embed location.

All resources must participate in the existing measurement / placement pipeline so they paginate correctly and respect keepWithNext-style constraints (resource + caption shouldn't split).

7. Warnings

Location: packages/postext-sandbox/src/warnings/compute.ts

• ::resource or :ref with an id that doesn't exist in the resources panel.
• Resource defined in the panel but never referenced in the markdown (unused resource).
• Resource id duplicated (two resources sharing an id).
• Inline :ref pointing at a resource whose typeId was deleted from the type list.
• Circular references (shouldn't be possible structurally but guard anyway).
• Bitmap at rendered size exceeds a resolution threshold relative to its native size (blurriness hint).

8. Bundle integration

Location: issue #47

The .postext bundle format must carry resources/ binaries and a resources/index.json with the resource metadata + table models. Resource types belong in config.json (they're configuration).

Acceptance criteria

• ResourceType list + editor UI in config settings
• Resource storage in IndexedDB, binaries by fileId
• Replace placeholder ResourcesPanel with upload / create / edit / delete UX
• Bitmap upload (PNG/JPEG/WebP/GIF) with preview and replace
• SVG upload with preview
• Table editor: add/remove rows/cols, col-span / row-span, header toggles, alignment, keyboard nav
• Table cells parsed with the same microformat pipeline as body text (bold, italic, code, inline math, inline :ref)
• Caption field per resource, using the same rich inline editor
• Markdown ::resource{id=...} block directive
• Markdown :ref{id=... style=... text=...} inline directive
• Resource numbering pipeline runs after parsing, assigns per-type counters in first-occurrence order
• Numbering respects per-type resetOn (none / h1 / h2 / …)
• Caption prefix and inline ref both pull from the same numbering map
• Canvas and PDF backends render bitmaps, SVGs (vector in PDF), and tables with captions
• Inline :ref is clickable and navigates to the embed in HTML; PDF emits a link annotation
• Warnings for unknown ids, unused resources, duplicated ids, dangling type references
• .postext bundle from #47 round-trips resources and types
• Docs updated (docs/document-format-en.mdx, docs/configuration-en.mdx, and -es) with the new directives and type management

Out of scope (follow-ups)

• Image editing (crop / resize / filters) inside the panel.
• Importing tables from CSV files as a first-class action (paste works).
• Video / audio resources.
• LaTeX-style figure floats / placement algorithms — resources render at their embed location for now.
• Footnote-style references.
• Lists of figures / lists of tables auto-generated at the start of the document.
• Bidirectional links (clicking the resource jumps to the first reference in text).
• Non-SVG vector formats (EPS, PDF-as-image).

Related code

• Placeholder panel: packages/postext-sandbox/src/sidebar/ResourcesPanel.tsx
• Inline parsing: packages/postext/src/parse/inlineFormatting.ts, packages/postext/src/parse/inlineMath.ts
• Block parsing: packages/postext/src/parse/blockParser.ts
• Existing numbering: packages/postext/src/numbering.ts
• Types: packages/postext/src/types.ts
• Canvas rendering: packages/postext/src/canvas-backend/blockRender.ts
• PDF rendering: packages/postext-pdf/src/pdf-backend/index.ts
• Storage: packages/postext-sandbox/src/storage/persistence.ts
• Warnings: packages/postext-sandbox/src/warnings/compute.ts

Related issues

• #44 — custom fonts (same IndexedDB-blob pattern)
• #46 — pagination / {h1} context for numbering templates
• #47 — project bundle (must round-trip resources + types)
• #48 — advanced heading designs (resource numbering shares the heading-context mechanism)

[drnachio]

Execution plan — Issue #49: Resources panel (images, SVGs, tables, typed numbering, inline references)

Target: single branch, one PR. Ship all 16 acceptance criteria together.
Link to issue: #49

---

Context

ResourcesPanel is a placeholder today. This work replaces it with a full resources system:

• Upload/manage bitmaps, SVGs, and HTML tables in the sandbox.
• A built-in table editor that reuses postext's inline microformats (bold, italic, code, inline math, :ref).
• Per-resource captions rendered as figure/table feet.
• A user-editable list of resource types (figure, table, diagram, …) with per-type auto-numbering format, reset scope, and counter format.
• Markdown syntax extension: ::resource{id="…"} block embed and :ref{id="…"} inline reference. Numbering follows order of first reference in the document, so inserting a new reference earlier auto-renumbers the rest.

Why now: postext already has parsed VDT blocks with a 'resource' type tag and a PostextResource metadata shape, but nothing renders them and there is no UX to create them. The numbering and parse infrastructure is in place for headings — resources follow the same shape and the issue explicitly says "extend/parallel, don't duplicate."

Scope decisions (confirmed with user):

• Build the IndexedDB blob store as part of this issue. Issue Support custom user-uploaded fonts alongside Google Fonts #44 (custom fonts) is not yet implemented, so the blob store is introduced here as a generic module; Support custom user-uploaded fonts alongside Google Fonts #44 will adopt it later.
• Bundle-format AC (Project import/export: plain .md in the editor, full .postext bundle from the sidebar #47) is deferred — schemas are designed so Project import/export: plain .md in the editor, full .postext bundle from the sidebar #47 only has to serialize them, but no encoder/decoder ships here. AC item "bundle round-trips resources" is checked off in Project import/export: plain .md in the editor, full .postext bundle from the sidebar #47, not Resources panel: images, SVGs, HTML tables with captions, typed numbering & inline references #49.
• One PR, not phased. Reviewer-friendliness managed via commit granularity.
• Tests are core-only (vitest in packages/postext). No React Testing Library infra in the sandbox for this issue.

---

Phase map (inside the single PR, as commit groups)

1. Types & storage foundations — schemas, IndexedDB blob store, sandbox context wiring.
2. Markdown extension — ::resource block directive, :ref inline directive, parser changes.
3. Resource numbering pipeline — mirrors numbering.ts; produces ResourceNumberingMap.
4. Resource-type config editor — new CollapsibleSection in ConfigPanel.
5. Resources panel UI — manager, uploaders, per-resource detail, caption editor.
6. Table model + editor — structural model, editor UX, TSV/CSV paste, keyboard nav.
7. Canvas + PDF rendering — bitmap, SVG, table blocks; captions; :ref inline links.
8. Warnings — new warning kinds.
9. Docs — docs/document-format-{en,es}.mdx, docs/configuration-{en,es}.mdx.
10. Tests — vitest coverage for parser, numbering, table model.

---

1. Types & storage foundations

Types — packages/postext/src/types.ts

• Rename the existing PostextResource (lines 1–10) to LegacyResource or simply replace. It is declared but not rendered anywhere, so replacement is safe.
• Add:

export interface ResourceType {
  id: string;                         // stable id, e.g. 'figure'
  name: string;
  namePlural?: string;
  shortLabel: string;                 // "fig."
  numberingTemplate: string;          // "{h1}.{n}" or "{n}"
  resetOn: 'never' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
  counterFormat: 'decimal' | 'roman-lower' | 'roman-upper' | 'alpha-lower' | 'alpha-upper';
  captionPrefix: string;              // "{shortLabel} {number}. "
}

export type ResourceKind = 'bitmap' | 'svg' | 'table';

export interface Resource {
  id: string;                 // slug-like, user-editable; unique per doc
  typeId: string;             // → ResourceType.id
  kind: ResourceKind;
  caption?: string;           // markdown microformats
  altText?: string;
  createdAt: number;
  updatedAt: number;
  bitmap?: { fileId: string; format: 'png' | 'jpeg' | 'webp' | 'gif'; width: number; height: number };
  svg?:    { fileId: string };
  table?:  { model: TableModel };
}

export interface TableCell {
  content: string;
  colSpan?: number;
  rowSpan?: number;
  isHeader?: boolean;
  align?: 'left' | 'center' | 'right';
  verticalAlign?: 'top' | 'middle' | 'bottom';
}

export interface TableModel {
  rows: TableCell[][];
  headerRowCount?: number;
}

• Extend PostextConfig (where the resolved config lives): add resourceTypes: ResourceType[] with built-in defaults (figure, table).
• Built-in defaults live in a new packages/postext/src/defaults/resourceTypes.ts (returns the two defaults with resetOn: 'h1', numberingTemplate: '{h1}.{n}').

Parse types — packages/postext/src/parse/types.ts

• Add 'resourceBlock' to ContentBlockType union (line 1).
• Extend ContentBlock with optional resourceId?: string.
• Extend InlineSpan with optional ref?: { resourceId: string; style?: 'default' | 'number' | 'full'; text?: string }. Use the same \uFFFC placeholder approach as inline math so sourceMap stays 1-to-1.

Blob store — new packages/postext-sandbox/src/storage/blobStore.ts

Generic IndexedDB store (not resource-specific; #44 will reuse).

// Object store: 'blobs', keyPath: 'fileId'
interface BlobRecord { fileId: string; contentType: string; bytes: ArrayBuffer; createdAt: number }
export async function putBlob(bytes: ArrayBuffer, contentType: string): Promise<string>;
export async function getBlob(fileId: string): Promise<BlobRecord | null>;
export async function deleteBlob(fileId: string): Promise<void>;
export async function listBlobs(): Promise<BlobRecord[]>;

DB name: postext-sandbox. Version: 1. Single store for now; migrations handled the usual way if added later.

Resources store — new packages/postext-sandbox/src/storage/resources.ts

Persists the Resource[] list. Storage choice: IndexedDB object store resources (keyPath: id) in the same postext-sandbox DB — avoids localStorage size limits that bitmaps would hit.

export async function loadResources(): Promise<Resource[]>;
export async function saveResource(r: Resource): Promise<void>;
export async function deleteResource(id: string, cascadeBlobs?: boolean): Promise<void>;

SandboxContext wiring — packages/postext-sandbox/src/context/SandboxContext.tsx

• Add resources: Resource[] to SandboxState (loaded async on init, not persisted via localStorage).
• Actions: SET_RESOURCES, UPSERT_RESOURCE, DELETE_RESOURCE.
• On UPSERT_RESOURCE / DELETE_RESOURCE: call saveResource / deleteResource in a useEffect (same debounce pattern as config).
• ResourceType[] lives in config.resourceTypes — follows the existing config path (localStorage, auto-saved).

---

2. Markdown extension

Block directive — packages/postext/src/parse/blockParser.ts

• Add regex: const RESOURCE_DIRECTIVE_RE = /^::resource\s*\{id="([^"]+)"\}\s*$/;
• Insert match in the main loop (after math fences, before headings).
• Emit a block with type: 'resourceBlock', resourceId: id, empty text/spans.

Inline directive — packages/postext/src/parse/inlineFormatting.ts

• Add a pre-pass (same layer as injectMathSpans) that finds :ref{...} occurrences:

:ref\{id="([^"]+)"(?:\s+style="(default|number|full)")?(?:\s+text="([^"]*)")?\}

• Replace each match with a \uFFFC placeholder and carry the resolved metadata on the corresponding InlineSpan.ref.
• Order of passes: refs → math → formatting. (Refs first so math inside a ref text="" doesn't fight.)

Backward compatibility

None required — both directives are net-new syntax that doesn't conflict with existing markdown.

---

3. Resource numbering pipeline

New — packages/postext/src/pipeline/resourceNumbering.ts

Mirror packages/postext/src/numbering.ts:

export interface ResourceNumberEntry {
  number: string;                  // "1.7"
  typeId: string;
  heading: { h1?: number; h2?: number; /* … */ };
}
export type ResourceNumberingMap = Record<string, ResourceNumberEntry>;

export function computeResourceNumbering(
  blocks: ContentBlock[],
  resourceTypes: ResourceType[],
  resources: Resource[],
  headingContext: HeadingContextArray,   // reuse from numbering.ts
): ResourceNumberingMap;

Algorithm:

1. Walk blocks in reading order, tracking the current heading context (already computed by computeHeadingNumbers).
2. For each encountered resourceId — whether from a resourceBlock or from an InlineSpan.ref — record a first-occurrence entry if not already numbered.
3. Partition occurrences by typeId. For each type, iterate occurrences in first-reference order, applying the type's resetOn rule against the heading context to reset n.
4. Render each counter through the type's numberingTemplate + counterFormat using the same template renderer as heading numbers — extract it from numbering.ts into a shared renderCounterTemplate() helper so both callers share code.

Pipeline wiring — packages/postext/src/pipeline/build.ts

After computeHeadingNumbers (~line 97), before the main loop:

const resourceNumbering = computeResourceNumbering(
  contentBlocks, resolved.resourceTypes, resourcesFromContext, headingContext,
);

Thread resourceNumbering through MeasurementInput so captions and inline refs resolve their rendered strings before measurement.

---

4. Resource-type config editor

New — packages/postext-sandbox/src/sidebar/config/ResourceTypesSection.tsx

Follow the ColorPaletteSection.tsx pattern exactly:

• CollapsibleSection wrapper (reuse controls/CollapsibleSection.tsx).
• Local state: editingId, draft fields.
• Add-entry via crypto.randomUUID() fallback helper already in ColorPalette.
• Per row: id (read-only once set), name, namePlural, shortLabel, numberingTemplate, resetOn select, counterFormat select, captionPrefix. Collapsible preview showing a rendered example (fig. 1.7.).
• Delete guarded by ConfirmPopover (reuse panels/ConfirmPopover.tsx). Deletion warns if any existing resource uses the type.
• Dispatch UPDATE_CONFIG with patched resourceTypes.

Register in ConfigPanel.tsx alongside the other sections.

Defaults on first load

SandboxProvider init: if config.resourceTypes is unset, populate with the built-in figure + table defaults from packages/postext/src/defaults/resourceTypes.ts.

---

5. Resources panel UI

Replace — packages/postext-sandbox/src/sidebar/ResourcesPanel.tsx

Layout (two-column inside the panel):

• Left: resource list grouped by ResourceType.name; bitmap thumbnails, glyphs for SVG/table; "New" menu (Upload image, Upload SVG, New table).
• Right (detail): when a resource is selected — id input (auto-suggested from filename/caption via slugify), type selector, caption editor (reuses the same inline-microformat input component as body text — create a lightweight InlineMarkdownInput in packages/postext-sandbox/src/controls/ that runs through parseInlineFormatting for preview), alt text, kind-specific controls.

New components

• panels/resources/ResourceList.tsx — grouped list.
• panels/resources/ResourceDetail.tsx — detail pane dispatcher.
• panels/resources/BitmapUploader.tsx — drag/drop + file input; decodes with createImageBitmap to extract width/height; stores blob via putBlob.
• panels/resources/SvgUploader.tsx — text/XML upload; sanity-check with DOMParser; stores blob.
• panels/resources/ResourcePreview.tsx — renders a mock embed (caption prefix applied) using the selected resource type.

Delete flow

Before deletion, scan the current markdown for ::resource{id="X"} and :ref{id="X"} occurrences (regex count). If >0, confirm warns "X is referenced N times in the document. Delete anyway?"

---

6. Table model + editor

New — packages/postext/src/table/model.ts (pure functions, unit-testable)

export function addRow(m: TableModel, at: number): TableModel;
export function addColumn(m: TableModel, at: number): TableModel;
export function removeRow(m: TableModel, at: number): TableModel;
export function removeColumn(m: TableModel, at: number): TableModel;
export function mergeCells(m: TableModel, range: CellRange): TableModel;
export function unmergeCell(m: TableModel, at: CellPos): TableModel;
export function setCellContent(m: TableModel, at: CellPos, content: string): TableModel;
export function setAlignment(m: TableModel, at: CellPos, align?: Align, vAlign?: VAlign): TableModel;
export function parseTSV(input: string): TableModel;   // fills from pasted TSV/CSV

All operations return new TableModel objects (FP-first, per project memory). Merge tracks the "primary" cell and marks spanned cells as hidden (hiddenBy?: CellPos) so rendering is straightforward.

New — packages/postext-sandbox/src/panels/resources/TableEditor/

• TableEditor.tsx — top-level, wires keyboard nav (Tab/Shift-Tab/arrows), undo/redo (stack of TableModel snapshots).
• TableEditorCell.tsx — single cell; uses the same InlineMarkdownInput component as the caption editor.
• TableEditorToolbar.tsx — add row/col, merge/split, header toggles, alignment, paste-TSV action.
• Keyboard:
  • Tab / Shift-Tab → next/prev cell (wraps rows).
  • Arrow keys → directional move.
  • Cmd/Ctrl+Z / Shift+Cmd/Ctrl+Z → undo / redo from the snapshot stack.
• Paste: on onPaste into a cell, detect TSV/CSV → call parseTSV → offer "paste as table" action that overwrites current model.

---

7. Canvas + PDF rendering

Shared resolution

Extend MeasurementInput (in pipeline/buildMeasurement.ts) with resources: Resource[] and resourceNumbering: ResourceNumberingMap. Block kind resolution (pipeline/buildBlockKind.ts) handles resourceBlock by attaching the resolved Resource and numbering to the VDT block (add vdtBlock.resource?: Resource and vdtBlock.resourceNumber?: string).

Measurement

• Bitmap / SVG: height = scaled height given column width (preserve aspect ratio, cap at column width). Caption height computed via measureRichBlock on the caption spans using the configured caption font.
• Table: column widths — equal split for v1 (per-column sizing deferred out of scope). For each cell, measure with measureRichBlock(cell.spans, …, cellWidth, lineHeight). Row height = max cell height within the row (accounting for rowspan).
• Resource + caption measured together; the pair's combined height is what goes to placement.

Placement

In pipeline/placement.ts, add keepTogether handling: if a resource+caption group's combined height fits in the remaining column space, place it; otherwise advance to next column/page. No mid-split for v1 (resources stay atomic — explicitly allowed by issue scope: "resources render at their embed location for now").

Canvas backend — packages/postext/src/canvas-backend/blockRender.ts

Add a branch before the existing line loop:

if (block.type === 'resource') {
  renderResourceBlock(ctx, block, columnWidth, columnX);
  return;
}

New renderResourceBlock.ts:

• bitmap → getBlob(fileId) (cached via WeakMap on the render context) → createImageBitmap → ctx.drawImage.
• svg → rasterize via <img src="data:image/svg+xml,…"> loaded to an offscreen canvas (cached per fileId).
• table → draw borders, cell backgrounds for headers, then delegate to the existing rich-text line renderer for each cell.
• Caption below using existing rich-text rendering with the prefix prepended.
• :ref inline segments: canvas has no click surface; render as a styled segment (color = link color from config). Accept that clickability is PDF-only for v1.

PDF backend — packages/postext-pdf/src/pdf-backend/blockRender.ts

Parallel renderResourceBlock.ts here:

• bitmap → pdf-lib's embedPng / embedJpg (WebP decoded to PNG via canvas). Cache PDFImage by fileId on the doc-scoped context.
• svg → vector path emission. Reuse the existing math SVG path emitter if suitable; otherwise use pdf-lib's raw operator stream. If vector proves too big for v1, fall back to raster and log a TODO comment in the file.
• table → draw lines + delegated cell rendering.
• Caption below.
• :ref inline: emit a link annotation via page.node.addAnnot(...) pointing at a named destination created at the ::resource embed. Named destinations keyed by resource.id.

---

8. Warnings — packages/postext-sandbox/src/warnings/compute.ts + warnings/types.ts

Add to WarningKind:

• unknownResourceId — ::resource or :ref references an id not in resources.
• unusedResource — resource defined but never referenced.
• duplicateResourceId — two resources share an id.
• danglingTypeRef — resource's typeId points at a deleted ResourceType.
• bitmapTooSmall — rendered width > bitmap.width * 1.5 (configurable constant).

Each new warning added to the compute functions and rendered in WarningsPanel.tsx with icon + detail strings (add labels to SandboxLabels).

Circular refs: structurally impossible (:ref doesn't embed), no code needed — note in a comment only if necessary.

---

9. Docs — docs/document-format-{en,es}.mdx, docs/configuration-{en,es}.mdx

document-format-* — new section after "Display math"

## Resources

### Block embed
::resource{id="lighthouse-diagram"}

### Inline reference
As shown in :ref{id="lighthouse-diagram"}, …

Options:
:ref{id="…" style="number"}   → 1.7
:ref{id="…" style="full"}     → Figure 1.7
:ref{id="…" text="see it"}    → see it

Explain first-reference numbering and the difference between embed vs. reference.

configuration-* — new "Resource types" section

Document the ResourceType shape, {h1}/{n} template tokens, resetOn, counterFormat, captionPrefix. Cross-link the heading numbering docs.

Spanish mirrors

Translate both sections in -es variants with matching structure.

---

10. Tests — vitest, core package only

All in packages/postext/src/__tests__/:

• parse/resourceDirective.test.ts — ::resource{id="x"} produces a resourceBlock with correct id; malformed inputs fall through to paragraph.
• parse/inlineRef.test.ts — :ref{...} variations: default, style=number, style=full, text="…"; mixed with bold/italic/math; placeholder char count matches span count.
• pipeline/resourceNumbering.test.ts — first-reference ordering (embed before ref, ref before embed, ref only, interleaved types); resetOn: 'h1' behavior; numberingTemplate rendering with {h1} / {n}; counter formats (decimal, roman, alpha).
• table/model.test.ts — add/remove row/col invariants; merge/unmerge (no orphaned hidden cells); TSV paste normalization; round-trip content preservation.
• defaults/resourceTypes.test.ts — built-in defaults have valid templates and non-empty prefixes.
• Update __tests__/exports.test.ts to include the new public types (Resource, ResourceType, TableModel, etc.).

No sandbox-UI tests in this PR (per user decision). Manual verification instructions below cover the UI.

---

Critical files to modify

postext core

• packages/postext/src/types.ts — add ResourceType, Resource, TableModel, TableCell; extend PostextConfig.
• packages/postext/src/parse/types.ts — add 'resourceBlock'; extend ContentBlock.resourceId, InlineSpan.ref.
• packages/postext/src/parse/blockParser.ts — ::resource directive.
• packages/postext/src/parse/inlineFormatting.ts — :ref directive pre-pass.
• packages/postext/src/numbering.ts — extract shared renderCounterTemplate helper.
• packages/postext/src/pipeline/resourceNumbering.ts — new.
• packages/postext/src/pipeline/build.ts — wire numbering + thread ResourceNumberingMap.
• packages/postext/src/pipeline/buildMeasurement.ts — thread resources + numbering.
• packages/postext/src/pipeline/buildBlockKind.ts — resolve resourceBlock → VDT 'resource'.
• packages/postext/src/canvas-backend/blockRender.ts — resource branch.
• packages/postext/src/canvas-backend/renderResourceBlock.ts — new.
• packages/postext/src/table/model.ts — new, pure functions.
• packages/postext/src/defaults/resourceTypes.ts — new.

postext-pdf

• packages/postext-pdf/src/pdf-backend/blockRender.ts — resource branch.
• packages/postext-pdf/src/pdf-backend/renderResourceBlock.ts — new.
• packages/postext-pdf/src/pdf-backend/links.ts — new, named-destination helpers.

postext-sandbox

• packages/postext-sandbox/src/storage/blobStore.ts — new, generic IndexedDB.
• packages/postext-sandbox/src/storage/resources.ts — new, resource CRUD.
• packages/postext-sandbox/src/context/SandboxContext.tsx — resources state, actions.
• packages/postext-sandbox/src/controls/InlineMarkdownInput.tsx — new, shared caption/cell editor.
• packages/postext-sandbox/src/sidebar/ResourcesPanel.tsx — replace.
• packages/postext-sandbox/src/sidebar/config/ResourceTypesSection.tsx — new.
• packages/postext-sandbox/src/sidebar/ConfigPanel.tsx — register section.
• packages/postext-sandbox/src/panels/resources/* — new (ResourceList, ResourceDetail, uploaders, preview, TableEditor subtree).
• packages/postext-sandbox/src/warnings/types.ts — new kinds.
• packages/postext-sandbox/src/warnings/compute.ts — collectors.
• packages/postext-sandbox/src/sidebar/WarningsPanel.tsx — render new kinds.

docs

• docs/document-format-en.mdx, docs/document-format-es.mdx
• docs/configuration-en.mdx, docs/configuration-es.mdx

---

Reused existing code (no duplication)

• numbering.ts:parseTemplate / formatNumeral — extracted into shared renderCounterTemplate, consumed by both heading and resource numbering.
• controls/CollapsibleSection.tsx — wraps the new ResourceTypesSection.
• panels/ConfirmPopover.tsx — delete confirms.
• measure/rich.ts:measureRichBlock — table cell and caption measurement.
• ColorPaletteSection.tsx editable-row pattern (id generator, editingId/draft state, update via UPDATE_CONFIG).
• storage/persistence.ts — downloadJson/readJsonFile if we ever want export/import of resource metadata (not in v1).
• parse/inlineFormatting.ts:injectMathSpans atomic-placeholder trick — replicated for :ref.

---

Verification

Unit — run in core package

cd packages/postext && pnpm vitest run

All new tests from Phase 10 must pass. Update __tests__/exports.test.ts snapshot for new exports.

Manual — sandbox UI

1. pnpm --filter postext-sandbox dev and open the sandbox in a browser.
2. Open the config panel, expand Resource types, add a new type "Diagram" with numberingTemplate: "{n}", resetOn: "never", counterFormat decimal, captionPrefix: "Diagram {number}. ".
3. Open the resources panel. Upload a PNG, an SVG, and create a new table with 3×3 cells, merge two cells, add inline math $x^2$ in a cell, set a caption.
4. In the markdown editor, write:

   # Section one
   ::resource{id="my-bitmap"}
   
   Text with :ref{id="my-table"} inline.
   
   # Section two
   ::resource{id="my-table"}

5. Verify in the canvas preview:
   • Bitmap renders with caption prefixed fig. 1.1. (or whatever the type configures).
   • Inline :ref renders with the correct number before the embed appears (first-reference-wins).
   • Second section's resource picks up resetOn: 'h1' counter semantics.
6. Trigger PDF generation; confirm:
   • Bitmap embedded.
   • SVG renders as vector (or raster fallback if the first pass lands that way — note the TODO).
   • Table lays out with merges correct.
   • Clicking :ref in the PDF jumps to the embed (named destination link annotation).
7. Break things on purpose: reference an id that doesn't exist, duplicate an id, delete a resource type that's in use. Confirm each produces the expected warning in the warnings panel and badge count increments.

Docs preview

Run the docs site locally (whatever pnpm --filter docs dev / equivalent the repo uses) and verify the new Resources sections render and internal links work in both en and es.

---

Explicitly out of scope (per issue)

Image editing, CSV file import (paste only), video/audio, LaTeX-style floats, footnote refs, auto-generated lists of figures, bidirectional links, non-SVG vector formats. Also deferred here: bundle round-trip (issue #47), sandbox-UI React tests.

---

Risk notes

• SVG-as-vector in PDF is the highest-risk single task. If pdf-lib operator emission proves infeasible in a reasonable timebox, fall back to rasterization and leave a TODO(#49-svg-vector) comment. The AC "SVGs (vector in PDF)" is then a known partial.
• Replacing PostextResource is a breaking type change. Grep confirmed it's declared but unused in rendering; a quick grep -r PostextResource before implementation will validate that assumption in case a downstream consumer exists.
• IndexedDB on first run needs graceful handling in private-browsing modes where IDB may be unavailable — the blob store should surface a clear error through a warning kind storageUnavailable.