@opengeni/artifact-tool 0.2.2

package/src/native-raster.ts

@@ -0,0 +1,141 @@
+const FONT_FILES_ENV = "OPENGENI_ARTIFACT_RASTER_FONT_FILES";
+const DEFAULT_FONT_FAMILY_ENV = "OPENGENI_ARTIFACT_RASTER_DEFAULT_FONT_FAMILY";
+const MAX_FONT_FILES = 16;
+const MAX_FONT_FILE_BYTES = 32 * 1024 * 1024;
+
+type ResvgOptions = {
+  background?: string;
+  fitTo?: { mode: "zoom"; value: number };
+  font: {
+    defaultFontFamily?: string;
+    fontFiles?: string[];
+    loadSystemFonts: boolean;
+  };
+};
+
+type ResvgRuntime = {
+  Resvg: new (svg: string, options: ResvgOptions) => { render(): { asPng(): Uint8Array } };
+};
+
+type FontAuthority = ResvgOptions["font"];
+
+let cachedFontAuthority: { key: string; value: Promise<FontAuthority> } | undefined;
+
+/**
+ * Rasterize with an explicit font authority when the host configures one.
+ * Resvg otherwise succeeds while silently dropping every glyph on minimal
+ * Linux images. Sandboxes pin regular/bold/italic-capable Liberation faces;
+ * desktop installs retain their native system-font fallback.
+ */
+export async function rasterizeSvgToPng(
+  svg: string,
+  options: Readonly<{ background?: string; zoom?: number }> = {},
+): Promise<Uint8Array> {
+  const [{ Resvg }, font] = await Promise.all([
+    importNativeRuntime<ResvgRuntime>("@resvg/resvg-js"),
+    rasterFontAuthority(),
+  ]);
+  const resvgOptions: ResvgOptions = {
+    ...(options.background === undefined ? {} : { background: options.background }),
+    ...(options.zoom === undefined
+      ? {}
+      : { fitTo: { mode: "zoom" as const, value: options.zoom } }),
+    font,
+  };
+  return Uint8Array.from(new Resvg(svg, resvgOptions).render().asPng());
+}
+
+async function importNativeRuntime<T>(specifier: string): Promise<T> {
+  return (await import(/* @vite-ignore */ specifier)) as T;
+}
+
+async function rasterFontAuthority(): Promise<FontAuthority> {
+  const environment = typeof process === "undefined" ? undefined : process.env;
+  const filesJson = environment?.[FONT_FILES_ENV];
+  const defaultFontFamily = environment?.[DEFAULT_FONT_FAMILY_ENV];
+  if (filesJson === undefined && defaultFontFamily === undefined) {
+    return { loadSystemFonts: true };
+  }
+  if (
+    !filesJson ||
+    filesJson.length > 8_192 ||
+    !defaultFontFamily?.trim() ||
+    defaultFontFamily.length > 128 ||
+    /[\u0000-\u001f\u007f]/u.test(defaultFontFamily)
+  ) {
+    throw new Error(`${FONT_FILES_ENV} and ${DEFAULT_FONT_FAMILY_ENV} must be configured together`);
+  }
+  const key = `${filesJson}\u0000${defaultFontFamily}`;
+  if (cachedFontAuthority?.key === key) return await cachedFontAuthority.value;
+  const value = validateConfiguredFontAuthority(filesJson, defaultFontFamily.trim());
+  cachedFontAuthority = { key, value };
+  return await value;
+}
+
+async function validateConfiguredFontAuthority(
+  filesJson: string,
+  defaultFontFamily: string,
+): Promise<FontAuthority> {
+  let requested: unknown;
+  try {
+    requested = JSON.parse(filesJson);
+  } catch {
+    throw new Error(`${FONT_FILES_ENV} must be a JSON array of absolute font file paths`);
+  }
+  if (
+    !Array.isArray(requested) ||
+    requested.length === 0 ||
+    requested.length > MAX_FONT_FILES ||
+    requested.some((path) => typeof path !== "string" || path.length === 0)
+  ) {
+    throw new Error(`${FONT_FILES_ENV} must contain 1-${MAX_FONT_FILES} font file paths`);
+  }
+
+  // Keep browser HTML/SVG render paths free of Node builtins. This function is
+  // reached only by the native PNG/WebP branches with an explicit authority.
+  const fileSystemSpecifier = "node:fs/promises";
+  const pathSpecifier = "node:path";
+  const [{ open, realpath, stat }, { isAbsolute }] = await Promise.all([
+    import(/* @vite-ignore */ fileSystemSpecifier) as Promise<typeof import("node:fs/promises")>,
+    import(/* @vite-ignore */ pathSpecifier) as Promise<typeof import("node:path")>,
+  ]);
+  const fontFiles = await Promise.all(
+    requested.map(async (path) => {
+      if (!isAbsolute(path)) throw new Error(`${FONT_FILES_ENV} paths must be absolute`);
+      const canonical = await realpath(path);
+      const metadata = await stat(canonical);
+      if (!metadata.isFile() || metadata.size === 0 || metadata.size > MAX_FONT_FILE_BYTES) {
+        throw new Error(`Configured artifact raster font is not a bounded regular file: ${path}`);
+      }
+      const handle = await open(canonical, "r");
+      try {
+        const signature = new Uint8Array(4);
+        const { bytesRead } = await handle.read(signature, 0, signature.byteLength, 0);
+        const tag = new TextDecoder().decode(signature);
+        if (
+          bytesRead !== 4 ||
+          (tag !== "OTTO" && tag !== "ttcf" && !sameBytes(signature, [0, 1, 0, 0]))
+        ) {
+          throw new Error(`Configured artifact raster font has an unsupported signature: ${path}`);
+        }
+      } finally {
+        await handle.close();
+      }
+      return canonical;
+    }),
+  );
+  if (new Set(fontFiles).size !== fontFiles.length) {
+    throw new Error(`${FONT_FILES_ENV} must not contain duplicate files`);
+  }
+  return {
+    defaultFontFamily,
+    fontFiles,
+    loadSystemFonts: false,
+  };
+}
+
+function sameBytes(actual: Uint8Array, expected: readonly number[]): boolean {
+  return (
+    actual.length === expected.length && actual.every((value, index) => value === expected[index])
+  );
+}

package/src/native.ts

@@ -0,0 +1,390 @@
+import {
+  EDITABLE_ARTIFACT_INTENT_VERSION,
+  SPREADSHEET_ARTIFACT_COMMAND_VERSION,
+  assertCanonicalSpreadsheetArtifactCommandBytes,
+  decodeEditableArtifactMutationIntent,
+  encodeEditableArtifactMutationIntent,
+  encodeSpreadsheetArtifactCommandBatch,
+  hashEditableArtifactMutationIntentBytes,
+  type EditableArtifactMutationIntent,
+  type SpreadsheetArtifactCommandBatch,
+} from "@opengeni/contracts/editable-artifacts";
+import {
+  ArtifactCollaborationSession,
+  ArtifactDocumentSession,
+  ArtifactKernelRuntime,
+  ArtifactPresentationSession,
+  ArtifactRuntimeError,
+  ArtifactTextLayoutSession,
+  type ArtifactKernelCapabilities,
+  type NativeArtifactRuntimeTarget,
+} from "./runtime";
+
+export {
+  SPREADSHEET_ARTIFACT_COMMAND_VERSION,
+  assertCanonicalSpreadsheetArtifactCommandBytes,
+  decodeSpreadsheetArtifactCommandBatch,
+  editableArtifactStableId,
+  encodeSpreadsheetArtifactCommandBatch,
+  spreadsheetSheetId,
+} from "@opengeni/contracts/editable-artifacts";
+export type {
+  EditableArtifactStableId,
+  SpreadsheetArtifactCommand,
+  SpreadsheetArtifactCommandBatch,
+  SpreadsheetCellInput,
+  SpreadsheetCellPoint,
+  SpreadsheetCellRange,
+  SpreadsheetSheetGeneration,
+  SpreadsheetSheetPrecondition,
+} from "@opengeni/contracts/editable-artifacts";
+
+export type NativeArtifactModality = "spreadsheet" | "document" | "presentation";
+
+export type NativeSpreadsheetIntentFields = Omit<
+  EditableArtifactMutationIntent,
+  | "envelopeVersion"
+  | "protocolVersion"
+  | "modelSchemaVersion"
+  | "commandProtocolVersion"
+  | "commandBytes"
+>;
+
+export type NativeSpreadsheetAuthorCommandsInput = Readonly<{
+  intent: NativeSpreadsheetIntentFields;
+  commands: SpreadsheetArtifactCommandBatch;
+  /** Exact authoritative OGACF001 base selected for this apply attempt. */
+  resolvedBaseBytes: Uint8Array;
+}>;
+
+export type NativeSpreadsheetAuthoredTransaction = Readonly<{
+  /** Exact canonical OGATX001 bytes passed to Rust. */
+  intentBytes: Uint8Array;
+  requestHash: string;
+  /** One whole canonical OGACO001 transaction returned by Rust. */
+  committedTransactionBytes: Uint8Array;
+}>;
+
+export type CreateNativeArtifactSessionInput = Readonly<{
+  modality: NativeArtifactModality;
+  replicaNamespace: bigint;
+}>;
+
+export type OpenNativeArtifactSessionInput = Readonly<{
+  modality: NativeArtifactModality;
+  snapshot: Uint8Array;
+}>;
+
+export type NativeArtifactSession =
+  | NativeSpreadsheetSession
+  | NativeDocumentSession
+  | NativePresentationSession;
+
+/**
+ * Synchronous Node/Bun production spreadsheet session backed only by the
+ * verified Rust N-API collaboration kernel. It never selects the TypeScript
+ * reference model and deliberately rejects a browser/WASM runtime; browsers
+ * use the asynchronous `@opengeni/sdk/editable-artifacts` Worker API.
+ */
+export class NativeSpreadsheetSession {
+  readonly kind = "native" as const;
+  readonly modality = "spreadsheet" as const;
+  readonly target: NativeArtifactRuntimeTarget;
+  readonly capabilities: ArtifactKernelCapabilities;
+  readonly buildIdentity: string;
+
+  private constructor(
+    private readonly runtime: ArtifactKernelRuntime,
+    private readonly session: ArtifactCollaborationSession,
+  ) {
+    requireNativeSpreadsheetRuntime(runtime);
+    this.target = runtime.target as NativeArtifactRuntimeTarget;
+    this.capabilities = runtime.capabilities;
+    this.buildIdentity = runtime.buildIdentity;
+  }
+
+  static create(
+    runtime: ArtifactKernelRuntime,
+    replicaNamespace: bigint,
+  ): NativeSpreadsheetSession {
+    requireNativeSpreadsheetRuntime(runtime);
+    return new NativeSpreadsheetSession(
+      runtime,
+      runtime.createCollaborationSession(replicaNamespace),
+    );
+  }
+
+  static open(runtime: ArtifactKernelRuntime, snapshot: Uint8Array): NativeSpreadsheetSession {
+    requireNativeSpreadsheetRuntime(runtime);
+    return new NativeSpreadsheetSession(runtime, runtime.openCollaborationSession(snapshot));
+  }
+
+  /**
+   * Authors one already-canonical mutation. Rust independently validates the
+   * exact OGATX/OGASC bytes, resolves typed operations, applies atomically, and
+   * returns the whole canonical OGACO transaction.
+   */
+  authorTransaction(intentBytes: Uint8Array, resolvedBaseBytes: Uint8Array): Uint8Array {
+    assertSpreadsheetIntent(intentBytes);
+    return this.session.authorTransaction(intentBytes, resolvedBaseBytes);
+  }
+
+  /** Encodes one identity-free typed command batch and authors it atomically. */
+  authorCommands(
+    input: NativeSpreadsheetAuthorCommandsInput,
+  ): NativeSpreadsheetAuthoredTransaction {
+    const commandBytes = encodeSpreadsheetArtifactCommandBatch(input.commands);
+    const intentBytes = encodeEditableArtifactMutationIntent({
+      ...input.intent,
+      envelopeVersion: EDITABLE_ARTIFACT_INTENT_VERSION,
+      protocolVersion: 1,
+      modelSchemaVersion: 1,
+      commandProtocolVersion: SPREADSHEET_ARTIFACT_COMMAND_VERSION,
+      commandBytes,
+    });
+    const requestHash = hashEditableArtifactMutationIntentBytes(intentBytes);
+    const committedTransactionBytes = this.authorTransaction(intentBytes, input.resolvedBaseBytes);
+    return Object.freeze({ intentBytes, requestHash, committedTransactionBytes });
+  }
+
+  /** Replays one whole authoritative OGACO transaction atomically. */
+  applyCommitted(committedTransactionBytes: Uint8Array): void {
+    this.session.applyCommitted(committedTransactionBytes);
+  }
+
+  /**
+   * Executes one canonical OGAKQ request. Typed viewport/metadata helpers use
+   * the shared contract codec; this raw method remains useful at server byte
+   * boundaries and never exposes a Rust object layout.
+   */
+  query(queryBytes: Uint8Array): Uint8Array {
+    return this.session.query(queryBytes);
+  }
+
+  snapshot(): Uint8Array {
+    return this.session.snapshot();
+  }
+
+  frontier(): Uint8Array {
+    return this.session.frontier();
+  }
+
+  stateHash(): string {
+    return this.session.stateHash();
+  }
+
+  revision(): bigint {
+    return this.session.revision();
+  }
+
+  fork(): NativeSpreadsheetSession {
+    return new NativeSpreadsheetSession(this.runtime, this.session.fork());
+  }
+
+  isClosed(): boolean {
+    return this.session.isClosed();
+  }
+
+  dispose(): void {
+    this.session.dispose();
+  }
+}
+
+/** Exact synchronous N-API structured-document byte session. */
+export class NativeDocumentSession {
+  readonly kind = "native" as const;
+  readonly modality = "document" as const;
+  readonly target: NativeArtifactRuntimeTarget;
+  readonly capabilities: ArtifactKernelCapabilities;
+  readonly buildIdentity: string;
+
+  private constructor(
+    private readonly runtime: ArtifactKernelRuntime,
+    private readonly session: ArtifactDocumentSession,
+  ) {
+    requireNativeRuntime(runtime);
+    this.target = runtime.target as NativeArtifactRuntimeTarget;
+    this.capabilities = runtime.capabilities;
+    this.buildIdentity = runtime.buildIdentity;
+  }
+
+  static create(runtime: ArtifactKernelRuntime, namespace: bigint): NativeDocumentSession {
+    requireNativeRuntime(runtime);
+    return new NativeDocumentSession(runtime, runtime.createDocumentSession(namespace));
+  }
+
+  static open(runtime: ArtifactKernelRuntime, snapshot: Uint8Array): NativeDocumentSession {
+    requireNativeRuntime(runtime);
+    return new NativeDocumentSession(runtime, runtime.openDocumentSession(snapshot));
+  }
+
+  applyCommands(commands: Uint8Array): Uint8Array {
+    return this.session.applyCommands(commands);
+  }
+  query(request: Uint8Array): Uint8Array {
+    return this.session.query(request);
+  }
+  snapshot(): Uint8Array {
+    return this.session.snapshot();
+  }
+  revision(): bigint {
+    return this.session.revision();
+  }
+  stateHash(): string {
+    return this.session.stateHash();
+  }
+  fork(): NativeDocumentSession {
+    return new NativeDocumentSession(this.runtime, this.session.fork());
+  }
+  isClosed(): boolean {
+    return this.session.isClosed();
+  }
+  dispose(): void {
+    this.session.dispose();
+  }
+}
+
+/** Exact synchronous N-API presentation byte session. */
+export class NativePresentationSession {
+  readonly kind = "native" as const;
+  readonly modality = "presentation" as const;
+  readonly target: NativeArtifactRuntimeTarget;
+  readonly capabilities: ArtifactKernelCapabilities;
+  readonly buildIdentity: string;
+
+  private constructor(
+    private readonly runtime: ArtifactKernelRuntime,
+    private readonly session: ArtifactPresentationSession,
+  ) {
+    requireNativeRuntime(runtime);
+    this.target = runtime.target as NativeArtifactRuntimeTarget;
+    this.capabilities = runtime.capabilities;
+    this.buildIdentity = runtime.buildIdentity;
+  }
+
+  static create(runtime: ArtifactKernelRuntime, namespace: bigint): NativePresentationSession {
+    requireNativeRuntime(runtime);
+    return new NativePresentationSession(runtime, runtime.createPresentationSession(namespace));
+  }
+
+  static open(runtime: ArtifactKernelRuntime, snapshot: Uint8Array): NativePresentationSession {
+    requireNativeRuntime(runtime);
+    return new NativePresentationSession(runtime, runtime.openPresentationSession(snapshot));
+  }
+
+  applyCommands(commands: Uint8Array): Uint8Array {
+    return this.session.applyCommands(commands);
+  }
+  query(request: Uint8Array): Uint8Array {
+    return this.session.query(request);
+  }
+  snapshot(): Uint8Array {
+    return this.session.snapshot();
+  }
+  revision(): bigint {
+    return this.session.revision();
+  }
+  stateHash(): string {
+    return this.session.stateHash();
+  }
+  fork(): NativePresentationSession {
+    return new NativePresentationSession(this.runtime, this.session.fork());
+  }
+  isClosed(): boolean {
+    return this.session.isClosed();
+  }
+  dispose(): void {
+    this.session.dispose();
+  }
+}
+
+/** Exact synchronous N-API retained-font text-layout session. */
+export class NativeTextLayoutSession {
+  readonly kind = "native" as const;
+  readonly modality = "text-layout" as const;
+  readonly target: NativeArtifactRuntimeTarget;
+  readonly capabilities: ArtifactKernelCapabilities;
+  readonly buildIdentity: string;
+
+  private constructor(
+    private readonly session: ArtifactTextLayoutSession,
+    runtime: ArtifactKernelRuntime,
+  ) {
+    requireNativeRuntime(runtime);
+    this.target = runtime.target as NativeArtifactRuntimeTarget;
+    this.capabilities = runtime.capabilities;
+    this.buildIdentity = runtime.buildIdentity;
+  }
+
+  static open(runtime: ArtifactKernelRuntime, fontBundle: Uint8Array): NativeTextLayoutSession {
+    requireNativeRuntime(runtime);
+    return new NativeTextLayoutSession(runtime.openTextLayoutSession(fontBundle), runtime);
+  }
+
+  layout(request: Uint8Array): Uint8Array {
+    return this.session.layout(request);
+  }
+  isClosed(): boolean {
+    return this.session.isClosed();
+  }
+  dispose(): void {
+    this.session.dispose();
+  }
+}
+
+/** Creates a production modality session; unsupported Rust modes fail closed. */
+export function createNativeArtifactSession(
+  runtime: ArtifactKernelRuntime,
+  input: CreateNativeArtifactSessionInput,
+): NativeArtifactSession {
+  if (input.modality === "spreadsheet") {
+    return NativeSpreadsheetSession.create(runtime, input.replicaNamespace);
+  }
+  if (input.modality === "document") {
+    return NativeDocumentSession.create(runtime, input.replicaNamespace);
+  }
+  return NativePresentationSession.create(runtime, input.replicaNamespace);
+}
+
+/** Opens a production modality session; unsupported Rust modes fail closed. */
+export function openNativeArtifactSession(
+  runtime: ArtifactKernelRuntime,
+  input: OpenNativeArtifactSessionInput,
+): NativeArtifactSession {
+  if (input.modality === "spreadsheet")
+    return NativeSpreadsheetSession.open(runtime, input.snapshot);
+  if (input.modality === "document") return NativeDocumentSession.open(runtime, input.snapshot);
+  return NativePresentationSession.open(runtime, input.snapshot);
+}
+
+function assertSpreadsheetIntent(intentBytes: Uint8Array): void {
+  const intent = decodeEditableArtifactMutationIntent(intentBytes);
+  if (
+    intent.envelopeVersion !== EDITABLE_ARTIFACT_INTENT_VERSION ||
+    intent.protocolVersion !== 1 ||
+    intent.modelSchemaVersion !== 1 ||
+    intent.commandProtocolVersion !== SPREADSHEET_ARTIFACT_COMMAND_VERSION
+  ) {
+    throw new ArtifactRuntimeError(
+      "ARTIFACT_RUNTIME_INCOMPATIBLE",
+      "Spreadsheet intent versions do not match the loaded production kernel",
+    );
+  }
+  assertCanonicalSpreadsheetArtifactCommandBytes(intent.commandBytes);
+  // Hashing decodes again by design and proves the exact outer bytes are an
+  // acceptable canonical request before they cross the native boundary.
+  hashEditableArtifactMutationIntentBytes(intentBytes);
+}
+
+function requireNativeSpreadsheetRuntime(runtime: ArtifactKernelRuntime): void {
+  requireNativeRuntime(runtime);
+}
+
+function requireNativeRuntime(runtime: ArtifactKernelRuntime): void {
+  if (runtime.kind !== "native" || runtime.target === "wasm-web") {
+    throw new ArtifactRuntimeError(
+      "ARTIFACT_RUNTIME_UNAVAILABLE",
+      "NativeSpreadsheetSession requires an exact local N-API kernel; browser editing uses @opengeni/sdk/editable-artifacts",
+    );
+  }
+}