@namahapdf/sheets 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,546 @@
+/**
+ * SheetModel — the parsed render model for `.xlsx` workbooks (Phase 3,
+ * PLATFORM_PLAN.md). Sparse by design: real spreadsheets are mostly empty
+ * cells, so rows and cells live in Maps keyed by 0-based indices.
+ *
+ * Formulas are **display-only**: `Cell.formula` carries the source text and
+ * `Cell.raw` the cached result Excel saved in `<v>` — there is deliberately no
+ * evaluator (the recalc contract is `fullCalcOnLoad` on write-back, Phase 4).
+ */
+/** `t` attribute of `<c>`: number, shared string, formula string, bool, error, inline, ISO date. */
+type CellType = 'n' | 's' | 'str' | 'b' | 'e' | 'inlineStr' | 'd';
+type Cell = {
+    /**
+     * Display-ready underlying value: shared/inline strings resolved to text,
+     * otherwise the raw `<v>` content (number serials as written).
+     */
+    raw: string;
+    type: CellType;
+    /** Formula source (without leading '='), when the cell has one. */
+    formula?: string;
+    /** Index into `Workbook.styles` (resolved cellXfs). */
+    styleIdx: number;
+};
+type Row = {
+    cells: Map<number, Cell>;
+    heightPt?: number;
+    hidden?: boolean;
+};
+/** 0-based inclusive rectangle. */
+type CellRange = {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+};
+type BorderEdge = {
+    style: string;
+    color?: string;
+};
+/** One resolved cellXfs entry — everything the renderer needs, pre-joined. */
+type CellStyle = {
+    /** Number-format code ('' = General). Builtin ids already resolved to codes. */
+    numFmt: string;
+    font: {
+        name: string;
+        sizePt: number;
+        bold: boolean;
+        italic: boolean;
+        underline: boolean;
+        /** CSS hex like '#1F2937', when specified. */
+        color?: string;
+    };
+    /** Solid fill CSS hex, when patternType="solid". */
+    fill?: string;
+    borders?: {
+        l?: BorderEdge;
+        r?: BorderEdge;
+        t?: BorderEdge;
+        b?: BorderEdge;
+    };
+    align?: {
+        h?: 'left' | 'center' | 'right';
+        v?: 'top' | 'center' | 'bottom';
+        wrap?: boolean;
+    };
+};
+type Sheet = {
+    name: string;
+    /** OPC part path, e.g. "xl/worksheets/sheet1.xml" (the XlsxAnchor.sheetPart). */
+    part: string;
+    /** Sparse rows, 0-based. */
+    rows: Map<number, Row>;
+    merges: CellRange[];
+    /** Custom column widths in Excel "character" units, 0-based col index. */
+    colWidthsChars: Map<number, number>;
+    defaultColWidthChars: number;
+    defaultRowHeightPt: number;
+    /** Used extent (rows/cols), from `<dimension>` or the data scan. */
+    rowCount: number;
+    colCount: number;
+    hidden: boolean;
+};
+type Workbook = {
+    sheets: Sheet[];
+    /** Resolved styles; `Cell.styleIdx` indexes here. Index 0 = default. */
+    styles: CellStyle[];
+    /** 1904 date system (Mac legacy). */
+    date1904: boolean;
+};
+/** Parse an A1 cell reference → 0-based row/col. */
+declare function refToRC(ref: string): {
+    row: number;
+    col: number;
+};
+/** 0-based row/col → A1 reference. */
+declare function rcToRef(row: number, col: number): string;
+/** Parse "B2:D5" (or a single "B2") → 0-based inclusive range. */
+declare function refToRange(ref: string): CellRange;
+
+declare class XlsxDocument {
+    private pkg;
+    private sharedStrings;
+    private styles;
+    private date1904;
+    private sheetRefs;
+    private cache;
+    private constructor();
+    static load(data: ArrayBuffer | Uint8Array): Promise<XlsxDocument>;
+    get sheetCount(): number;
+    get sheetNames(): string[];
+    get is1904(): boolean;
+    get cellStyles(): CellStyle[];
+    /** Parse (and cache) one worksheet. */
+    sheet(index: number): Promise<Sheet>;
+    /** Eagerly parse everything (small workbooks / tests / doc-model export). */
+    workbook(): Promise<Workbook>;
+    private readWorkbook;
+    private readSharedStrings;
+    private readStyles;
+    private parseWorksheet;
+    private parseCell;
+}
+
+/**
+ * Excel number-format subset — formats a cell's cached value for display.
+ *
+ * In-house on purpose (no SheetJS `ssf` vendoring): covers the formats that
+ * dominate real workbooks — General, fixed decimals, thousands separators,
+ * percent, currency literals, dates/times from serials, text section — and
+ * falls back to a General rendering for anything exotic. Formatting must
+ * never throw: worst case the raw value is shown.
+ */
+declare function serialToDate(serial: number, date1904: boolean): Date;
+/** Does this format code render a date/time? */
+declare const isDateFormat: (code: string) => boolean;
+/** General rendering for numbers: trim floating noise, up to ~11 significant digits. */
+declare function generalNumber(value: number): string;
+/**
+ * Format a cell value for display.
+ * `value` is the decoded raw (`Cell.raw`); booleans/errors/text pass through.
+ */
+declare function formatValue(raw: string, type: 'n' | 's' | 'str' | 'b' | 'e' | 'inlineStr' | 'd', numFmt: string, date1904?: boolean): string;
+
+declare const HEADER_W = 46;
+declare const HEADER_H = 24;
+type GridMetrics = {
+    rows: number;
+    cols: number;
+    totalW: number;
+    totalH: number;
+    colX: (c: number) => number;
+    rowY: (r: number) => number;
+    colW: (c: number) => number;
+    rowH: (r: number) => number;
+    colAt: (x: number) => number;
+    rowAt: (y: number) => number;
+};
+/**
+ * Prefix-sum metrics over sparse custom sizes: O(#custom) memory, O(log n)
+ * lookups — the sparse maps stay the source of truth.
+ */
+declare function buildMetrics(sheet: Sheet): GridMetrics;
+type SheetViewport = {
+    scrollX: number;
+    scrollY: number;
+    widthPx: number;
+    heightPx: number;
+    /** devicePixelRatio (canvas backing scale). */
+    dpr: number;
+};
+declare class SheetRenderer {
+    private sheet;
+    private styles;
+    private date1904;
+    readonly metrics: GridMetrics;
+    /** Merge lookup: anchor "r,c" → range; covered (non-anchor) cells "r,c". */
+    private mergeAnchor;
+    private mergeCovered;
+    constructor(sheet: Sheet, styles: CellStyle[], date1904: boolean);
+    formatted(cell: Cell): string;
+    render(canvas: HTMLCanvasElement, vp: SheetViewport, dark?: boolean): void;
+}
+
+/**
+ * Canonical, format-neutral document model.
+ *
+ * Both PPTX (via the existing structure projector) and PDF normalize into this
+ * shape so one set of projectors (Markdown / chunks) and the knowledge base feed
+ * off a single representation. Designed to also accept DOCX later.
+ *
+ * Geometry is optional `BBox` in PDF points, top-left origin. Image/chart
+ * elements carry KB-enrichment fields (`ocrText`, `caption`, `summary`) that the
+ * vision pipeline fills in (Track 5).
+ */
+
+type BBox = {
+    xPt: number;
+    yPt: number;
+    wPt: number;
+    hPt: number;
+};
+
+/**
+ * Edit anchors — serializable locators that tie a structural element back to a
+ * concrete editable location in the native file.
+ *
+ * Anchors deliberately carry no live object references and no byte offsets:
+ * they cross the API boundary as plain JSON, and the writer/dispatcher
+ * re-derives the concrete operators (PDF content-stream indices, OOXML nodes)
+ * fresh at apply time by re-rendering / re-parsing. This mirrors how PDF edits
+ * already work (operator indices captured at render time) and how the PPTX
+ * writer will re-open the raw XML rather than trust the lossy parsed tree.
+ */
+
+/** Locator into a .pptx part. Built in Track C; consumed by the writer in Track D. */
+type PptxAnchor = {
+    fmt: 'pptx';
+    /** e.g. "ppt/slides/slide3.xml" */
+    slidePart: string;
+    /** cNvPr/@id — stable within a slide part. */
+    shapeId?: string;
+    /** Fallback locator: 0-based shape index in p:spTree. */
+    spTreeIndex?: number;
+    /** Text edits: paragraph index within the shape's txBody. */
+    paraIndex?: number;
+    /** ...then run index within that paragraph. */
+    runIndex?: number;
+    /** Table cell. */
+    cell?: {
+        row: number;
+        col: number;
+    };
+    /** Image: the blip r:embed relationship id. */
+    relId?: string;
+    /** Image: resolved media part path (e.g. "ppt/media/image2.png"). */
+    mediaPart?: string;
+};
+/**
+ * Locator into a PDF. The dispatcher re-renders the page at apply time and
+ * relocates the run by text (operator indices are never carried across the
+ * boundary, so they can't go stale).
+ */
+type PdfAnchor = {
+    fmt: 'pdf';
+    pageIndex: number;
+    /** Element/run text used to relocate the target run at apply time. */
+    text?: string;
+    /** Geometry in PDF points, top-left origin (informational / planner hints). */
+    bbox?: BBox;
+};
+/**
+ * Locator into a .xlsx workbook. Rows/cols are 0-based; the writer resolves the
+ * A1-style cell reference (`<c r="B3">`) inside the worksheet part at apply time.
+ */
+type XlsxAnchor = {
+    fmt: 'xlsx';
+    /** e.g. "xl/worksheets/sheet1.xml" */
+    sheetPart: string;
+    /** Display name of the sheet (informational / planner hint). */
+    sheetName?: string;
+    /** 0-based row index. */
+    row: number;
+    /** 0-based column index. */
+    col: number;
+    /** Optional 0-based inclusive range for region-level intents. */
+    range?: {
+        r1: number;
+        c1: number;
+        r2: number;
+        c2: number;
+    };
+};
+type EditAnchor = PptxAnchor | PdfAnchor | XlsxAnchor;
+
+/**
+ * Format-neutral edit intents — the stable middle of the editing pipeline.
+ *
+ * Everything above the dispatcher (planner, API, bulk runner, UI) speaks only
+ * `EditIntent` / `EditPlan`. `dispatch.ts` is the only place that knows how to
+ * route an intent to a concrete engine (PDFEditSession for PDF, PptxWriter for
+ * PPTX). Intents are JSON-serializable so they cross the API boundary; the
+ * `find-replace` intent is anchor-free (located per file at apply time).
+ */
+
+type EditIntent = {
+    op: 'replace-text';
+    anchor: EditAnchor;
+    newText: string;
+} | {
+    op: 'replace-image';
+    anchor: EditAnchor;
+    bytes: Uint8Array;
+    format: 'png' | 'jpeg';
+    mode?: 'swap-part' | 'repoint';
+} | {
+    op: 'set-cell';
+    anchor: EditAnchor;
+    row: number;
+    col: number;
+    newText: string;
+} | {
+    op: 'find-replace';
+    find: string;
+    replace: string;
+    scope?: 'all' | number[];
+} | {
+    op: 'move-shape';
+    anchor: EditAnchor;
+    xPt?: number;
+    yPt?: number;
+} | {
+    op: 'resize-shape';
+    anchor: EditAnchor;
+    wPt?: number;
+    hPt?: number;
+} | {
+    op: 'add-slide';
+    afterIndex?: number;
+} | {
+    op: 'delete-slide';
+    index: number;
+} | {
+    op: 'reorder-slide';
+    from: number;
+    to: number;
+} | {
+    op: 'add-text-box';
+    anchor: EditAnchor;
+    xPt: number;
+    yPt: number;
+    wPt: number;
+    hPt: number;
+    text: string;
+    sizePt?: number;
+} | {
+    op: 'clear-cell';
+    anchor: EditAnchor;
+    row: number;
+    col: number;
+} | {
+    op: 'format-cell';
+    anchor: EditAnchor;
+    row: number;
+    col: number;
+    format: CellFormatPatch;
+} | {
+    op: 'set-column-width';
+    anchor: EditAnchor;
+    col: number;
+    widthChars: number;
+};
+/**
+ * Partial formatting for `format-cell` — unset fields inherit the cell's
+ * current style. The writer never mutates a shared style entry; it appends.
+ */
+type CellFormatPatch = {
+    bold?: boolean;
+    italic?: boolean;
+    /** Number-format code, e.g. '0.00', '#,##0', 'm/d/yyyy'. */
+    numFmt?: string;
+    /** Solid fill as CSS hex '#RRGGBB'. */
+    fill?: string;
+};
+type EditPlan = {
+    source: {
+        fileName: string;
+        format: 'pptx' | 'pdf' | 'xlsx';
+    };
+    intents: EditIntent[];
+};
+/** Per-intent outcome reported back from the dispatcher. */
+type IntentResult = {
+    op: EditIntent['op'];
+    ok: boolean;
+    applied: number;
+    error?: string;
+    /** Op-specific payload, e.g. the new slide part path from `add-slide` (for anchoring follow-up intents). */
+    detail?: string;
+};
+type EditResult = {
+    bytes: Uint8Array;
+    results: IntentResult[];
+};
+
+/**
+ * Apply an edit plan to a `.xlsx`. Returns the edited bytes (the unchanged
+ * input when nothing applied) plus a per-intent result log.
+ */
+declare function applyXlsxPlan(bytes: Uint8Array, plan: EditPlan): Promise<EditResult>;
+
+/**
+ * XlsxEditSession — the framework-free editing session behind the sheet
+ * editor UI, mirroring `pptx/edit/PptxEditSession` (P1/P3 of PLATFORM_PLAN.md).
+ *
+ * Intent-sourced: the UI never mutates the parsed model. It calls
+ * `apply(intents)`; the writer splices the current bytes (`applyXlsxPlan`),
+ * the session snapshots the result, re-parses, and notifies subscribers,
+ * which re-render from the *saved* truth. Undo/redo replay byte snapshots.
+ */
+
+type SessionListener = () => void;
+declare class XlsxEditSession {
+    readonly fileName: string;
+    /** Byte snapshots; `cursor` points at the current state, entries after it are redo states. */
+    private snapshots;
+    private cursor;
+    private parsed;
+    private listeners;
+    /** Every intent ever applied, in order (serializable audit / AI parity log). */
+    readonly intentLog: EditIntent[];
+    private constructor();
+    static load(fileName: string, bytes: Uint8Array): Promise<XlsxEditSession>;
+    /** Current file bytes (the saved truth). */
+    get bytes(): Uint8Array;
+    /** Current parsed workbook. */
+    get doc(): XlsxDocument;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    subscribe(listener: SessionListener): () => void;
+    private notify;
+    /**
+     * Apply intents to the current bytes. When anything lands, a new snapshot
+     * becomes current, redo is cleared, and the workbook is re-parsed. Failed
+     * intents are reported per-intent, never thrown.
+     */
+    apply(intents: EditIntent[]): Promise<IntentResult[]>;
+    undo(): Promise<boolean>;
+    redo(): Promise<boolean>;
+    /** Current bytes as a downloadable Blob. */
+    toBlob(): Blob;
+}
+
+/**
+ * Zod schemas for the edit contract — the validation boundary between an
+ * (untrusted) LLM-emitted `EditPlan` and the dispatcher (PLATFORM_PLAN.md
+ * Phase 5). Two consumers:
+ *
+ * 1. **Runtime validation** — `validateEditPlan(json)` at `/api/edit/apply`
+ *    (and any agent host) rejects malformed plans with readable errors before
+ *    a single intent runs.
+ * 2. **Tool definitions** — `editPlanJsonSchema()` emits a JSON Schema an agent
+ *    framework can hand an LLM verbatim as the arguments schema for an
+ *    "apply document edits" tool. The model then emits plans that validate.
+ *
+ * The schemas mirror the `EditIntent` / `EditAnchor` unions in this directory
+ * exactly; keep them in lockstep when the unions change (the round-trip test
+ * asserts every op is covered). `replace-image` carries binary bytes, so it is
+ * `z.any()` here — image replacement uses a binary channel, not pure JSON.
+ */
+
+type ValidatedPlan = {
+    ok: true;
+    plan: EditPlan;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Validate an untrusted value as an `EditPlan`. On success returns the typed
+ * plan; on failure a flat list of `path: message` strings (safe to surface to
+ * the caller / feed back to the model).
+ */
+declare function validateEditPlan(input: unknown): ValidatedPlan;
+/**
+ * JSON Schema for the whole `EditPlan` — hand this to an agent framework as the
+ * arguments schema of an "apply document edits" tool. Binary/unrepresentable
+ * fields (`replace-image.bytes`) render as permissive `{}`.
+ */
+declare function editPlanJsonSchema(): Record<string, unknown>;
+
+/** Shared license/activation contracts used by both the engine gate and the server. */
+/** Capabilities a license can unlock. `view`/`annotate` are the always-available base. */
+type LicenseFeature = 'view' | 'annotate' | 'edit-text' | 'sign' | 'redact' | 'forms' | 'export-clean' | 'pptx-edit' | 'sheets-view' | 'sheets-edit';
+type LicenseEdition = 'trial' | 'pro' | 'enterprise';
+type LicenseStatus = 'UNLICENSED' | 'INVALID' | 'LICENSED' | 'GRACE' | 'DEGRADED';
+interface LicenseState {
+    status: LicenseStatus;
+    edition: LicenseEdition | null;
+    features: LicenseFeature[];
+    /** True when render/export should be watermarked. */
+    watermark: boolean;
+    /** Human-readable reason (for diagnostics; never user-facing copy). */
+    reason: string;
+}
+
+/**
+ * Client-side license gate for the NamahaPDF engine.
+ *
+ * Flow (see configureLicense):
+ *   1. Verify the license key OFFLINE (signature, expiry, domain) — instant, no network.
+ *   2. If a cached activation token is still valid → LICENSED immediately.
+ *   3. Kick a NON-BLOCKING background activation that exchanges the key for a fresh,
+ *      short-TTL activation token (which is also what the server can revoke).
+ *
+ * Offline grace is weighted heavily on purpose: transient network/server failures
+ * never punish a paying customer. We tolerate up to MAX_FAILURES (5) attempts AND a
+ * BOOTSTRAP_GRACE window before degrading — the SDK degrades immediately ONLY on an
+ * explicit signed `revoked`/`invalid` from the server.
+ *
+ * Everything is injectable (storage / fetch / clock / public key) so it is unit-testable
+ * without a browser or a server.
+ */
+
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+interface LicenseConfig {
+    /** The signed license key the developer received. */
+    licenseKey?: string;
+    /** Activation endpoint. Defaults to a same-origin `/api/license/activate`. */
+    activationUrl?: string;
+    /** Stable per-install id; auto-generated + persisted when omitted. */
+    deviceId?: string;
+    /** First-party bypass — our own app passes this so it never watermarks itself. */
+    owner?: boolean;
+    /** Override the embedded public key (tests only). */
+    publicKeyHex?: string;
+    /** Injected clock (tests). */
+    now?: () => number;
+    /** Injected storage (tests / Node). */
+    storage?: StorageLike;
+    /** Injected fetch (tests / Node). */
+    fetchImpl?: typeof fetch;
+    /** Host to domain-check against; defaults to location.hostname in the browser. */
+    host?: string;
+    /** Background retry backoff in ms (tests can shorten). */
+    retryDelays?: number[];
+}
+type Listener = (s: LicenseState) => void;
+/**
+ * Configure (or reconfigure) the license gate. Verifies the key synchronously and
+ * starts a background activation. Returns the immediate state; subscribe with
+ * `onLicenseChange` for updates as activation completes.
+ */
+declare function configureLicense(config?: LicenseConfig): LicenseState;
+/** Current license state (synchronous, cheap). */
+declare function getLicenseState(): LicenseState;
+declare function isFeatureEnabled(feature: LicenseFeature): boolean;
+/** Throws if a feature is not licensed — use to guard gated engine operations. */
+declare function assertFeature(feature: LicenseFeature): void;
+declare function shouldWatermark(): boolean;
+/** Subscribe to state changes (activation success/failure). Returns an unsubscribe. */
+declare function onLicenseChange(cb: Listener): () => void;
+
+export { type BorderEdge, type Cell, type CellFormatPatch, type CellRange, type CellStyle, type CellType, type EditAnchor, type EditIntent, type EditPlan, type EditResult, type GridMetrics, HEADER_H, HEADER_W, type IntentResult, type LicenseConfig, type LicenseEdition, type LicenseFeature, type LicenseState, type LicenseStatus, type Row, type Sheet, SheetRenderer, type SheetViewport, type Workbook, type XlsxAnchor, XlsxDocument, XlsxEditSession, applyXlsxPlan, assertFeature, buildMetrics, configureLicense, editPlanJsonSchema, formatValue, generalNumber, getLicenseState, isDateFormat, isFeatureEnabled, onLicenseChange, rcToRef, refToRC, refToRange, serialToDate, shouldWatermark, validateEditPlan };