@smallpen/local-package 0.1.0-alpha.1

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@smallpen/local-package",
+  "version": "0.1.0-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": "./src/index.mjs",
+  "files": [
+    "assets",
+    "src"
+  ],
+  "dependencies": {
+    "@jsquash/webp": "1.5.0",
+    "@smallpen/core": "0.1.0-alpha.1",
+    "opentype.js": "2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SmallRaw/SmallPen.git",
+    "directory": "smallpen/packages/local-package"
+  }
+}

package/src/draft-import.mjs

@@ -0,0 +1,282 @@
+import { randomUUID } from "node:crypto";
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { inflateSync, zstdDecompressSync } from "node:zlib";
+
+import {
+  canonicalJSON,
+  createFigmaDraftValues,
+  createFlatDraftValues,
+  fail,
+  listPackageEntries,
+  loadPackageFromValues,
+  sha256Hex,
+  SmallPenError,
+} from "@smallpen/core";
+
+import {
+  ByteBuffer,
+  compileSchema,
+  decodeBinarySchema,
+} from "./kiwi-runtime.mjs";
+
+const MAX_INPUT_BYTES = 50 * 1024 * 1024;
+const MAX_DECOMPRESSED_BYTES = 128 * 1024 * 1024;
+const ZSTD_MAGIC = [0x28, 0xb5, 0x2f, 0xfd];
+
+function decodeBase64(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    fail("invalid_figma_clipboard", `${label} is missing`);
+  }
+  const bytes = Buffer.from(value.replace(/\s+/g, ""), "base64");
+  if (bytes.byteLength === 0 || bytes.byteLength > MAX_INPUT_BYTES) {
+    fail("invalid_figma_clipboard", `${label} is empty or too large`);
+  }
+  return new Uint8Array(bytes);
+}
+
+function parseFigKiwiChunks(binary) {
+  if (
+    binary.byteLength < 20 ||
+    new TextDecoder("ascii").decode(binary.slice(0, 8)) !== "fig-kiwi"
+  ) {
+    fail("invalid_figma_clipboard", "Figma clipboard payload is not fig-kiwi");
+  }
+  const view = new DataView(binary.buffer, binary.byteOffset, binary.byteLength);
+  const chunks = [];
+  let offset = 12;
+  while (offset < binary.byteLength) {
+    if (offset + 4 > binary.byteLength) {
+      fail("invalid_figma_clipboard", "Figma clipboard chunk header is truncated");
+    }
+    const length = view.getUint32(offset, true);
+    offset += 4;
+    if (length <= 0 || offset + length > binary.byteLength) {
+      fail("invalid_figma_clipboard", "Figma clipboard chunk length is invalid");
+    }
+    chunks.push(binary.slice(offset, offset + length));
+    offset += length;
+  }
+  if (chunks.length < 2) {
+    fail("invalid_figma_clipboard", "Figma clipboard requires schema and data chunks");
+  }
+  return chunks;
+}
+
+function isZstd(bytes) {
+  return ZSTD_MAGIC.every((byte, index) => bytes[index] === byte);
+}
+
+function decompress(bytes, label) {
+  try {
+    const result = isZstd(bytes)
+      ? zstdDecompressSync(bytes, { maxOutputLength: MAX_DECOMPRESSED_BYTES })
+      : inflateSync(bytes, { maxOutputLength: MAX_DECOMPRESSED_BYTES });
+    return new Uint8Array(result);
+  } catch (error) {
+    fail(
+      "invalid_figma_clipboard",
+      `Unable to decompress Figma ${label}: ${error.message}`,
+    );
+  }
+}
+
+export async function decodeFigmaClipboard(html) {
+  if (typeof html !== "string" || Buffer.byteLength(html) > MAX_INPUT_BYTES) {
+    fail("invalid_figma_clipboard", "Figma clipboard HTML is invalid or too large");
+  }
+  const metaMatch = /\(figmeta\)(.*?)\(\/figmeta\)/s.exec(html);
+  const bufferMatch = /\(figma\)(.*?)\(\/figma\)/s.exec(html);
+  if (!metaMatch || !bufferMatch) {
+    fail(
+      "invalid_figma_clipboard",
+      "Input does not contain Figma structured clipboard markers",
+    );
+  }
+  let meta;
+  try {
+    meta = JSON.parse(Buffer.from(metaMatch[1], "base64").toString("utf8"));
+  } catch (error) {
+    fail("invalid_figma_clipboard", `Figma clipboard metadata is invalid: ${error.message}`);
+  }
+  const chunks = parseFigKiwiChunks(decodeBase64(bufferMatch[1], "Figma clipboard payload"));
+  try {
+    const schema = decodeBinarySchema(new ByteBuffer(decompress(chunks[0], "schema")));
+    const compiled = compileSchema(schema);
+    if (typeof compiled.decodeMessage !== "function") {
+      fail("invalid_figma_clipboard", "Figma clipboard schema has no Message decoder");
+    }
+    const message = compiled.decodeMessage(decompress(chunks[1], "data"));
+    const nodeChanges = message.nodeChanges ?? [];
+    if (!Array.isArray(nodeChanges)) {
+      fail("invalid_figma_clipboard", "Figma clipboard nodeChanges are invalid");
+    }
+    return {
+      blobCount: Array.isArray(message.blobs) ? message.blobs.length : 0,
+      meta,
+      nodeChanges,
+    };
+  } catch (error) {
+    if (error instanceof SmallPenError) throw error;
+    fail("invalid_figma_clipboard", `Unable to decode Figma clipboard: ${error.message}`);
+  }
+}
+
+function inspectPng(bytes) {
+  const signature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+  if (
+    bytes.byteLength < 24 ||
+    signature.some((byte, index) => bytes[index] !== byte) ||
+    new TextDecoder("ascii").decode(bytes.slice(12, 16)) !== "IHDR"
+  ) {
+    fail("invalid_draft_media", "Draft PNG has an invalid signature or IHDR");
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return { height: view.getUint32(20), width: view.getUint32(16) };
+}
+
+function inspectSvg(bytes) {
+  let source;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch (error) {
+    fail("invalid_draft_media", `Draft SVG is not UTF-8: ${error.message}`);
+  }
+  const root = /<svg\b([^>]*)>/i.exec(source)?.[1];
+  if (root === undefined) fail("invalid_draft_media", "Draft SVG has no svg root");
+  const attribute = (name) =>
+    new RegExp(`\\b${name}\\s*=\\s*["']([^"']+)["']`, "i").exec(root)?.[1];
+  const length = (value) => {
+    const match = /^\s*([0-9]+(?:\.[0-9]+)?)(?:px)?\s*$/i.exec(value ?? "");
+    return match ? Math.round(Number(match[1])) : undefined;
+  };
+  let width = length(attribute("width"));
+  let height = length(attribute("height"));
+  const viewBox = attribute("viewBox")?.trim().split(/[\s,]+/).map(Number);
+  if ((!width || !height) && viewBox?.length === 4 && viewBox.every(Number.isFinite)) {
+    width ??= Math.round(viewBox[2]);
+    height ??= Math.round(viewBox[3]);
+  }
+  if (!Number.isSafeInteger(width) || width <= 0 || !Number.isSafeInteger(height) || height <= 0) {
+    fail("invalid_draft_media", "Draft SVG dimensions are invalid");
+  }
+  return { height, width };
+}
+
+async function pathExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function writeDraftPackage(outputValue, values) {
+  const output = resolve(outputValue);
+  if (!output.endsWith(".smallpen")) {
+    fail("invalid_draft_path", "Draft output must end in .smallpen", { output });
+  }
+  if (await pathExists(output)) {
+    fail("draft_output_exists", "Draft output already exists and will not be overwritten", {
+      output,
+    });
+  }
+  await mkdir(dirname(output), { recursive: true });
+  const transaction = await mkdtemp(join(dirname(output), ".smallpen-draft-"));
+  const candidate = join(transaction, `${basename(output)}-${randomUUID()}.smallpen`);
+  try {
+    const loaded = await loadPackageFromValues(candidate, values);
+    await mkdir(candidate);
+    const { entries } = listPackageEntries(loaded.manifest);
+    for (const entry of ["manifest.json", ...entries]) {
+      const path = join(candidate, entry);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(
+        path,
+        canonicalJSON(entry === "manifest.json" ? loaded.manifest : loaded.entries[entry]),
+        "utf8",
+      );
+    }
+    for (const [entry, bytes] of loaded.blobs) {
+      const path = join(candidate, entry);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, bytes);
+    }
+    if (await pathExists(output)) {
+      fail("draft_output_exists", "Draft output appeared during import and was not overwritten", {
+        output,
+      });
+    }
+    await rename(candidate, output);
+    await rm(transaction, { force: true, recursive: true });
+    return { ...loaded, locator: output };
+  } catch (error) {
+    await rm(transaction, { force: true, recursive: true });
+    throw error;
+  }
+}
+
+export async function importDraft({
+  bytes,
+  html,
+  importedAt = new Date().toISOString(),
+  kind,
+  output,
+  packageId = "pkg_figma_draft",
+}) {
+  if (!new Set(["figma", "png", "svg"]).has(kind)) {
+    fail("invalid_draft_kind", "Draft import kind must be figma, svg, or png");
+  }
+  let model;
+  if (kind === "figma") {
+    const input = new TextEncoder().encode(html ?? "");
+    const decoded = await decodeFigmaClipboard(html);
+    model = createFigmaDraftValues({
+      importedAt,
+      inputHash: await sha256Hex(input),
+      meta: decoded.meta,
+      nodeChanges: decoded.nodeChanges,
+      packageId,
+    });
+    if (decoded.blobCount > 0) {
+      model.losses.push({
+        code: "figma_binary_blobs_not_embedded",
+        message: `${decoded.blobCount} Figma binary image/font blobs remain source-only in this Draft`,
+        severity: "warning",
+      });
+      model.values.get("manifest.json").draft.losses = model.losses;
+    }
+  } else {
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0 || bytes.byteLength > MAX_INPUT_BYTES) {
+      fail("invalid_draft_media", "Draft fallback bytes are empty or too large");
+    }
+    const dimensions = kind === "png" ? inspectPng(bytes) : inspectSvg(bytes);
+    const inputHash = await sha256Hex(bytes);
+    model = createFlatDraftValues({
+      bytes,
+      ...dimensions,
+      importedAt,
+      inputHash,
+      mimeType: kind === "png" ? "image/png" : "image/svg+xml",
+      packageId,
+      sourceKind: kind,
+    });
+  }
+  const written = await writeDraftPackage(output, model.values);
+  return {
+    losses: model.losses,
+    output: written.locator,
+    packageId: written.manifest.packageId,
+    provenance: model.provenance,
+    revision: written.revision,
+  };
+}

package/src/font-convert.mjs

@@ -0,0 +1,132 @@
+import { deflateSync } from "node:zlib";
+
+import { SmallPenError } from "@smallpen/core";
+
+// SFNT -> WOFF repackaging shared by the CLI and the Background font service.
+
+const FONT_SIGNATURES = {
+  "font/otf": new Uint8Array([0x4f, 0x54, 0x54, 0x4f]),
+  "font/ttf": new Uint8Array([0x00, 0x01, 0x00, 0x00]),
+  "font/woff": new Uint8Array([0x77, 0x4f, 0x46, 0x46]),
+  "font/woff2": new Uint8Array([0x77, 0x4f, 0x46, 0x32]),
+};
+
+function failFont(code, message, details) {
+  throw new SmallPenError(code, message, details);
+}
+
+function matches(bytes, signature) {
+  return signature.every((value, index) => bytes[index] === value);
+}
+
+export function inspectFont(bytes, mimeType) {
+  const signature = FONT_SIGNATURES[mimeType];
+  if (!signature || !matches(bytes, signature)) {
+    failFont(
+      "invalid_font_blob",
+      `Font bytes do not match ${mimeType || "an allowed Font type"}`,
+      { mimeType },
+    );
+  }
+  return mimeType;
+}
+
+function align4(value) {
+  return (value + 3) & ~3;
+}
+
+function tableRecords(bytes) {
+  if (bytes.byteLength < 12) {
+    failFont("invalid_font_blob", "SFNT Font header is truncated");
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const numTables = view.getUint16(4, false);
+  const directoryEnd = 12 + numTables * 16;
+  if (numTables === 0 || numTables > 4096 || directoryEnd > bytes.byteLength) {
+    failFont("invalid_font_blob", "SFNT Font table directory is invalid");
+  }
+  const records = [];
+  for (let index = 0; index < numTables; index += 1) {
+    const position = 12 + index * 16;
+    const offset = view.getUint32(position + 8, false);
+    const length = view.getUint32(position + 12, false);
+    if (offset > bytes.byteLength || length > bytes.byteLength - offset) {
+      failFont("invalid_font_blob", "SFNT Font table extends beyond the file");
+    }
+    records.push({
+      checksum: view.getUint32(position + 4, false),
+      data: bytes.subarray(offset, offset + length),
+      length,
+      tag: view.getUint32(position, false),
+    });
+  }
+  return records.sort((left, right) => left.tag - right.tag);
+}
+
+export function sfntToWoff(bytes, mimeType) {
+  if (mimeType !== "font/ttf" && mimeType !== "font/otf") {
+    failFont("unsupported_font_conversion", `Cannot convert ${mimeType} to WOFF`);
+  }
+  inspectFont(bytes, mimeType);
+  const source = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const records = tableRecords(bytes).map((record) => {
+    const compressed = new Uint8Array(deflateSync(record.data));
+    return {
+      ...record,
+      stored: compressed.byteLength < record.length ? compressed : record.data,
+    };
+  });
+  const directoryLength = 44 + records.length * 20;
+  let outputLength = directoryLength;
+  for (const record of records) outputLength += align4(record.stored.byteLength);
+  const output = new Uint8Array(outputLength);
+  const view = new DataView(output.buffer);
+  view.setUint32(0, 0x774f4646, false);
+  view.setUint32(4, source.getUint32(0, false), false);
+  view.setUint32(8, outputLength, false);
+  view.setUint16(12, records.length, false);
+  view.setUint16(14, 0, false);
+  view.setUint32(
+    16,
+    12 + records.length * 16 +
+      records.reduce((total, record) => total + align4(record.length), 0),
+    false,
+  );
+  view.setUint16(20, 1, false);
+  view.setUint16(22, 0, false);
+  let dataOffset = directoryLength;
+  for (const [index, record] of records.entries()) {
+    const position = 44 + index * 20;
+    view.setUint32(position, record.tag, false);
+    view.setUint32(position + 4, dataOffset, false);
+    view.setUint32(position + 8, record.stored.byteLength, false);
+    view.setUint32(position + 12, record.length, false);
+    view.setUint32(position + 16, record.checksum, false);
+    output.set(record.stored, dataOffset);
+    dataOffset += align4(record.stored.byteLength);
+  }
+  return output;
+}
+
+export function prepareFontFiles(input) {
+  const files = {};
+  for (const [mimeType, bytes] of Object.entries(input)) {
+    inspectFont(bytes, mimeType);
+    const format = mimeType.slice("font/".length);
+    files[format] = { bytes, mimeType };
+  }
+  if (!files.woff) {
+    const source = files.ttf ?? files.otf;
+    if (!source) {
+      failFont(
+        "unsupported_font_conversion",
+        "A WOFF2-only upload cannot be converted without a WOFF2 decoder",
+      );
+    }
+    files.woff = {
+      bytes: sfntToWoff(source.bytes, source.mimeType),
+      mimeType: "font/woff",
+    };
+  }
+  return files;
+}

package/src/index.mjs

@@ -0,0 +1,34 @@
+export { LocalPackageBackend } from "./local-package-backend.mjs";
+export {
+  LocalWorkspaceSession,
+  reconcilePackageViewState,
+} from "./local-workspace-session.mjs";
+export { openWorkspace, resolveWorkspace } from "./workspace.mjs";
+export {
+  defaultLibraryCacheRoot,
+  openRemoteLibrary,
+} from "./remote-library.mjs";
+export { createEvidence, renderProjection } from "./render.mjs";
+export {
+  decodeFigmaClipboard,
+  importDraft,
+  writeDraftPackage,
+} from "./draft-import.mjs";
+export { createBlankPackage, initializeWorkspace } from "./initialize.mjs";
+export {
+  applyOperationBatch,
+  deleteFontFamily,
+  deleteFontVariant,
+  importFontVariant,
+  importMedia,
+  openPackage,
+  removeMedia,
+  replayRecordedBatch,
+  updateFontFamily,
+} from "./local-package.mjs";
+export { detectMediaType, inspectMedia } from "./media-inspect.mjs";
+export {
+  inspectFont,
+  prepareFontFiles,
+  sfntToWoff,
+} from "./font-convert.mjs";