@opengeni/artifact-tool 0.2.2

package/dist/snapshot.js

@@ -0,0 +1,61 @@
+import {
+  requireCompositeState
+} from "./chunk-HTJBLBDE.js";
+import {
+  NativeDocumentSession,
+  NativePresentationSession,
+  NativeSpreadsheetSession
+} from "./chunk-B2ZJRZDA.js";
+import "./chunk-N2IHNWBS.js";
+import "./chunk-VUNV25KB.js";
+
+// src/snapshot.ts
+import {
+  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+  EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,
+  EDITABLE_ARTIFACT_SNAPSHOT_VERSION
+} from "@opengeni/contracts/editable-artifact-versions";
+function createArtifactSnapshot(artifact) {
+  const state = requireCompositeState(artifact);
+  const native = state.native;
+  const common = {
+    schemaVersion: 1,
+    modality: state.modality,
+    runtimeTarget: native.target,
+    kernelVersion: native.buildIdentity,
+    modelSchemaVersion: EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,
+    snapshotVersion: EDITABLE_ARTIFACT_SNAPSHOT_VERSION,
+    stateHash: native.stateHash(),
+    snapshotBytes: Uint8Array.from(native.snapshot())
+  };
+  if (state.modality === "spreadsheet") {
+    if (!(native instanceof NativeSpreadsheetSession)) {
+      throw new Error("Spreadsheet composite does not own a spreadsheet native session");
+    }
+    return Object.freeze({
+      ...common,
+      modality: "spreadsheet",
+      coveredCausalFrontierBytes: Uint8Array.from(native.frontier()),
+      operationProtocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+      crdtStateVersion: EDITABLE_ARTIFACT_SNAPSHOT_VERSION
+    });
+  }
+  if (!(native instanceof NativeDocumentSession) && !(native instanceof NativePresentationSession)) {
+    throw new Error("Serialized composite does not own its expected native session");
+  }
+  return Object.freeze({
+    ...common,
+    modality: state.modality,
+    nativeRevision: safeNativeRevision(native.revision())
+  });
+}
+function safeNativeRevision(value) {
+  if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError("Artifact native revision exceeds the durable range");
+  }
+  return Number(value);
+}
+export {
+  createArtifactSnapshot
+};
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/snapshot.ts"],"sourcesContent":["import {\n  COMMITTED_TRANSACTION_PROTOCOL_VERSION,\n  EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,\n  EDITABLE_ARTIFACT_SNAPSHOT_VERSION,\n} from \"@opengeni/contracts/editable-artifact-versions\";\nimport type { Document } from \"./document\";\nimport {\n  NativeDocumentSession,\n  NativePresentationSession,\n  NativeSpreadsheetSession,\n} from \"./native\";\nimport type { Presentation } from \"./presentation\";\nimport { requireCompositeState } from \"./production-composite\";\nimport type { Workbook } from \"./spreadsheet\";\n\ntype ArtifactSnapshotCommon = Readonly<{\n  schemaVersion: 1;\n  modality: \"spreadsheet\" | \"document\" | \"presentation\";\n  runtimeTarget: string;\n  kernelVersion: string;\n  modelSchemaVersion: 1;\n  snapshotVersion: 1;\n  stateHash: string;\n  snapshotBytes: Uint8Array;\n}>;\n\n/** Exact native-canonical state at one durable artifact boundary. */\nexport type ArtifactSnapshot =\n  | (ArtifactSnapshotCommon &\n      Readonly<{\n        modality: \"spreadsheet\";\n        coveredCausalFrontierBytes: Uint8Array;\n        operationProtocolVersion: 1;\n        crdtStateVersion: 1;\n      }>)\n  | (ArtifactSnapshotCommon &\n      Readonly<{\n        modality: \"document\" | \"presentation\";\n        nativeRevision: number;\n      }>);\n\n/** Capture one immutable native snapshot from an open artifact object. */\nexport function createArtifactSnapshot(\n  artifact: Workbook | Document | Presentation,\n): ArtifactSnapshot {\n  const state = requireCompositeState(artifact);\n  const native = state.native;\n  const common = {\n    schemaVersion: 1 as const,\n    modality: state.modality,\n    runtimeTarget: native.target,\n    kernelVersion: native.buildIdentity,\n    modelSchemaVersion: EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,\n    snapshotVersion: EDITABLE_ARTIFACT_SNAPSHOT_VERSION,\n    stateHash: native.stateHash(),\n    snapshotBytes: Uint8Array.from(native.snapshot()),\n  };\n  if (state.modality === \"spreadsheet\") {\n    if (!(native instanceof NativeSpreadsheetSession)) {\n      throw new Error(\"Spreadsheet composite does not own a spreadsheet native session\");\n    }\n    return Object.freeze({\n      ...common,\n      modality: \"spreadsheet\" as const,\n      coveredCausalFrontierBytes: Uint8Array.from(native.frontier()),\n      operationProtocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,\n      crdtStateVersion: EDITABLE_ARTIFACT_SNAPSHOT_VERSION,\n    });\n  }\n  if (\n    !(native instanceof NativeDocumentSession) &&\n    !(native instanceof NativePresentationSession)\n  ) {\n    throw new Error(\"Serialized composite does not own its expected native session\");\n  }\n  return Object.freeze({\n    ...common,\n    modality: state.modality,\n    nativeRevision: safeNativeRevision(native.revision()),\n  });\n}\n\nfunction safeNativeRevision(value: bigint): number {\n  if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) {\n    throw new RangeError(\"Artifact native revision exceeds the durable range\");\n  }\n  return Number(value);\n}\n"],"mappings":";;;;;;;;;;;;AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAsCA,SAAS,uBACd,UACkB;AAClB,QAAM,QAAQ,sBAAsB,QAAQ;AAC5C,QAAM,SAAS,MAAM;AACrB,QAAM,SAAS;AAAA,IACb,eAAe;AAAA,IACf,UAAU,MAAM;AAAA,IAChB,eAAe,OAAO;AAAA,IACtB,eAAe,OAAO;AAAA,IACtB,oBAAoB;AAAA,IACpB,iBAAiB;AAAA,IACjB,WAAW,OAAO,UAAU;AAAA,IAC5B,eAAe,WAAW,KAAK,OAAO,SAAS,CAAC;AAAA,EAClD;AACA,MAAI,MAAM,aAAa,eAAe;AACpC,QAAI,EAAE,kBAAkB,2BAA2B;AACjD,YAAM,IAAI,MAAM,iEAAiE;AAAA,IACnF;AACA,WAAO,OAAO,OAAO;AAAA,MACnB,GAAG;AAAA,MACH,UAAU;AAAA,MACV,4BAA4B,WAAW,KAAK,OAAO,SAAS,CAAC;AAAA,MAC7D,0BAA0B;AAAA,MAC1B,kBAAkB;AAAA,IACpB,CAAC;AAAA,EACH;AACA,MACE,EAAE,kBAAkB,0BACpB,EAAE,kBAAkB,4BACpB;AACA,UAAM,IAAI,MAAM,+DAA+D;AAAA,EACjF;AACA,SAAO,OAAO,OAAO;AAAA,IACnB,GAAG;AAAA,IACH,UAAU,MAAM;AAAA,IAChB,gBAAgB,mBAAmB,OAAO,SAAS,CAAC;AAAA,EACtD,CAAC;AACH;AAEA,SAAS,mBAAmB,OAAuB;AACjD,MAAI,QAAQ,MAAM,QAAQ,OAAO,OAAO,gBAAgB,GAAG;AACzD,UAAM,IAAI,WAAW,oDAAoD;AAAA,EAC3E;AACA,SAAO,OAAO,KAAK;AACrB;","names":[]}

package/dist/spreadsheet-address.d.ts

@@ -0,0 +1,18 @@
+export declare const EXCEL_MAX_ROWS = 1048576;
+export declare const EXCEL_MAX_COLUMNS = 16384;
+export type CellAddress = {
+    row: number;
+    col: number;
+};
+export type RangeAddress = CellAddress & {
+    rowCount: number;
+    colCount: number;
+};
+export declare function columnNameToIndex(name: string): number;
+export declare function columnIndexToName(index: number): string;
+export declare function parseCellAddress(input: string): CellAddress;
+export declare function parseRangeAddress(input: string): RangeAddress;
+export declare function formatCellAddress(address: CellAddress): string;
+export declare function formatRangeAddress(address: RangeAddress): string;
+export declare function cellKey(row: number, col: number): number;
+export declare function assertRange(address: RangeAddress): void;

package/dist/spreadsheet-file.d.ts

@@ -0,0 +1,17 @@
+import type { FileBlob } from "./file-blob.js";
+import type { Workbook } from "./spreadsheet.js";
+import { SpreadsheetFidelityError, SpreadsheetSecurityError, type SpreadsheetFidelityIssue, type SpreadsheetLossPreservationEnvelope, type SpreadsheetXlsxExportOptions, type SpreadsheetXlsxImportLimits, type SpreadsheetXlsxImportOptions } from "./spreadsheet-xlsx-api.js";
+export { SpreadsheetFidelityError, SpreadsheetSecurityError, type SpreadsheetFidelityIssue, type SpreadsheetLossPreservationEnvelope, type SpreadsheetXlsxExportOptions, type SpreadsheetXlsxImportLimits, type SpreadsheetXlsxImportOptions, };
+/** Lazily loaded XLSX codec around the canonical Workbook model. */
+export declare class SpreadsheetFile {
+    static importXlsx(input: FileBlob | Blob | ArrayBuffer | Uint8Array, options?: SpreadsheetXlsxImportOptions): Promise<Workbook>;
+    static exportXlsx(workbook: Workbook, options?: SpreadsheetXlsxExportOptions): Promise<FileBlob>;
+    static fidelityReport(workbook: Workbook): readonly SpreadsheetFidelityIssue[];
+    /**
+     * Returns a portable copy of the opaque original-package envelope.
+     * Persist it beside Workbook.toJSON(); the Workbook JSON intentionally does not contain Office bytes.
+     */
+    static lossPreservationEnvelope(workbook: Workbook): SpreadsheetLossPreservationEnvelope | null;
+    /** Reattaches a separately persisted envelope to a restored canonical workbook snapshot. */
+    static attachLossPreservationEnvelope(workbook: Workbook, envelope: SpreadsheetLossPreservationEnvelope, options?: Pick<SpreadsheetXlsxImportOptions, "limits">): Promise<void>;
+}

package/dist/spreadsheet-formula.d.ts

@@ -0,0 +1,67 @@
+import { type CellAddress } from "./spreadsheet-address.js";
+import type { FormulaResult } from "./spreadsheet-types.js";
+export type FormulaReference = {
+    sheetName: string | null;
+    start: CellAddress;
+    end: CellAddress;
+};
+export type FormulaEvaluationContext = {
+    currentSheetName: string;
+    getCell: (sheetName: string, address: CellAddress) => FormulaResult;
+    /** Reuse one budget across recursively evaluated dependency formulas. */
+    budget?: FormulaEvaluationBudget;
+    /** Applied only when `budget` is omitted. */
+    limits?: Partial<FormulaEvaluationLimits>;
+};
+export type FormulaEvaluationLimits = {
+    maxFormulaBytes: number;
+    maxTokens: number;
+    maxNestingDepth: number;
+    maxFunctionArguments: number;
+    maxRangeCells: number;
+    maxCellReads: number;
+    maxOperations: number;
+    maxDependencyDepth: number;
+    maxResultStringChars: number;
+};
+/** Conservative reference-engine boundaries. Native kernels must enforce equivalent or tighter caps. */
+export declare const DEFAULT_FORMULA_LIMITS: Readonly<FormulaEvaluationLimits>;
+/** Explicit, shareable fuel for one root formula evaluation. */
+export declare class FormulaEvaluationBudget {
+    readonly limits: Readonly<FormulaEvaluationLimits>;
+    private operationsUsed;
+    private cellReadsUsed;
+    constructor(overrides?: Partial<FormulaEvaluationLimits>);
+    consumeOperations(count?: number): void;
+    consumeCellReads(count: number): void;
+    assertDependencyDepth(depth: number): void;
+    get usage(): Readonly<{
+        operations: number;
+        cellReads: number;
+    }>;
+    get operationCount(): number;
+    get cellReadCount(): number;
+    /**
+     * Reuse this meter for one independent root without exposing a reset primitive. Re-entry is
+     * rejected, including from a hostile `getCell` callback during `evaluateFormula`.
+     */
+    runIsolatedRoot<T>(evaluate: (budget: FormulaEvaluationBudget) => T): T;
+    /**
+     * Activate one trusted batch while retaining an independent fuel counter for every root.
+     * The scoped runner expires with the batch and cannot be used for active-root re-entry.
+     */
+    runIsolatedRoots<T>(evaluateBatch: (runRoot: <R>(evaluate: (budget: FormulaEvaluationBudget) => R) => R) => T): T;
+}
+export declare function evaluateFormula(formula: string, context: FormulaEvaluationContext): FormulaResult;
+/** Validate resource bounds without materializing ranges or reading workbook cells. */
+export declare function validateFormulaLimits(formula: string, limits?: Partial<FormulaEvaluationLimits>): void;
+/**
+ * Fail closed unless the complete formula is valid reference-engine syntax and every function
+ * belongs to the explicit bounded allowlist. Unlike `validateFormulaLimits`, syntax faults are
+ * rejected instead of being treated as ordinary spreadsheet error values.
+ */
+export declare function validateSupportedFormula(formula: string, limits?: Partial<FormulaEvaluationLimits>): void;
+export declare function referencesInFormula(formula: string): FormulaReference[];
+export declare function translateFormula(formula: string, rowDelta: number, colDelta: number): string;
+export declare function formulaFromR1C1(formula: string, anchor: CellAddress): string;
+export declare function formulaToR1C1(formula: string, anchor: CellAddress): string;

package/dist/spreadsheet-image.d.ts

@@ -0,0 +1,17 @@
+import type { SpreadsheetImageConfig } from "./spreadsheet-types.js";
+export type SpreadsheetRasterImageContentType = "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+/** Untrusted spreadsheet image input was rejected before render or file export. */
+export declare class InvalidSpreadsheetImageError extends Error {
+    readonly field: string;
+    readonly code = "INVALID_SPREADSHEET_IMAGE";
+    constructor(field: string, detail: string);
+}
+/**
+ * Copies, validates, and freezes a spreadsheet image at the model boundary.
+ *
+ * Both byte and data-URL inputs become a canonical immutable data URL. This
+ * prevents later caller mutation and lets render/export reuse validation in O(1).
+ */
+export declare function normalizeSpreadsheetImageConfig(input: SpreadsheetImageConfig): SpreadsheetImageConfig;
+/** Returns a validated inline source and never fetches or reads external data. */
+export declare function spreadsheetImageSource(input: SpreadsheetImageConfig): string;

package/dist/spreadsheet-render.d.ts

@@ -0,0 +1,5 @@
+import { FileBlob } from "./file-blob.js";
+import type { Workbook } from "./spreadsheet.js";
+import type { RenderSpreadsheetOptions } from "./spreadsheet-types.js";
+/** Render the canonical workbook model without requiring Excel or LibreOffice. */
+export declare function renderWorkbook(workbook: Workbook, options?: RenderSpreadsheetOptions): Promise<FileBlob>;