akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/packages/core/src/acl.ts

@@ -0,0 +1,272 @@
+
+
+/** A scope entry: field → glob. The plugin says which fields it knows (its manifest `scope`). */
+export type ScopeEntry = Record<string, string>;
+
+export interface AclGrant {
+  plugin: string;
+  /** Window ids (1 = the main window), or every window. Mobile and web pages are window 1. */
+  windows: "*" | number[];
+  /** Methods, `listen:<event>` for subscriptions, or everything. */
+  items: "*" | string[];
+  /** Absent: no restriction from this grant. */
+  allow?: ScopeEntry[];
+  deny?: ScopeEntry[];
+}
+
+export interface ResolvedAcl {
+  grants: AclGrant[];
+  /** plugin → items denied everywhere. */
+  denied?: Record<string, string[]>;
+}
+
+/** What a call may touch. `allow: null`: anything the plugin allows by itself, minus `deny`. */
+export interface CallScope {
+  allow: ScopeEntry[] | null;
+  deny: ScopeEntry[];
+}
+
+export interface Access {
+  allowed: boolean;
+  /** Only when some matching grant carries scopes. */
+  scope?: CallScope;
+}
+
+/** What hosts enforce when boot.json's ACL is broken: nothing is allowed (fail-closed). */
+export const DENY_ALL: ResolvedAcl = { grants: [], denied: {} };
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const isStrings = (v: unknown): v is string[] => Array.isArray(v) && v.every((s) => typeof s === "string");
+const isScopes = (v: unknown) =>
+  v === undefined ||
+  (Array.isArray(v) && v.every((e) => isRecord(e) && Object.values(e).every((s) => typeof s === "string")));
+
+/**
+ * Why an ACL from boot.json is not one the hosts can enforce, or null. Every host checks the same
+ * shape (Swift AkanNativeAcl.from, Kotlin AkanNativeAcl.from; vectors/acl.json): a malformed part must not
+ * loosen the rest, as when one bad denial dropped every denial or one bad grant allowed everything.
+ */
+export function aclProblem(value: unknown): string | null {
+  if (!isRecord(value) || !Array.isArray(value.grants)) return "acl must be { grants: [...], denied?: {...} }";
+  for (const [i, g] of value.grants.entries()) {
+    if (!isRecord(g) || typeof g.plugin !== "string" || g.plugin === "") return `grant ${i} has no plugin`;
+    if (
+      g.windows !== "*" &&
+      !(Array.isArray(g.windows) && g.windows.every((w) => Number.isInteger(w) && (w as number) >= 1))
+    )
+      return `grant ${i}: bad windows`;
+    if (g.items !== "*" && !isStrings(g.items)) return `grant ${i}: bad items`;
+    if (!isScopes(g.allow) || !isScopes(g.deny)) return `grant ${i}: bad scopes`;
+  }
+  if (value.denied !== undefined && !(isRecord(value.denied) && Object.values(value.denied).every(isStrings)))
+    return "bad denied";
+  return null;
+}
+
+/**
+ * A host's ACL from its boot data. boot.json without one (a build without capabilities, unit
+ * tests): null, everything allowed. One that is not well formed: nothing allowed.
+ */
+export function loadAcl(boot: { acl?: unknown }): { acl: ResolvedAcl | null; problem: string | null } {
+  if (!("acl" in boot) || boot.acl === undefined) return { acl: null, problem: null };
+  const problem = aclProblem(boot.acl);
+  return problem ? { acl: DENY_ALL, problem } : { acl: boot.acl as ResolvedAcl, problem: null };
+}
+
+/** The ACL item of a `$listen` for `event`. */
+export const listenItem = (event: string) => `listen:${event}`;
+
+/**
+ * The C7 check. Without an ACL (older builds, unit tests) everything is allowed, as before PL-11.
+ */
+export function aclCheck(acl: ResolvedAcl | undefined | null, plugin: string, item: string, window = 1): Access {
+  if (!acl) return { allowed: true };
+  if (acl.denied?.[plugin]?.includes(item)) return { allowed: false };
+  const matching = acl.grants.filter(
+    (g) =>
+      g.plugin === plugin &&
+      (g.items === "*" || g.items.includes(item)) &&
+      (g.windows === "*" || g.windows.includes(window)),
+  );
+  if (matching.length === 0) return { allowed: false };
+  const allow = matching.some((g) => !g.allow) ? null : matching.flatMap((g) => g.allow!);
+  const deny = matching.flatMap((g) => g.deny ?? []);
+  return allow === null && deny.length === 0 ? { allowed: true } : { allowed: true, scope: { allow, deny } };
+}
+
+const cache = new Map<string, RegExp>();
+
+/** The anchored regex for `source`, compiled once. `u`: `?` is one character, not one UTF-16 unit. */
+function compiled(source: string): RegExp {
+  let re = cache.get(source);
+  if (!re) {
+    re = new RegExp(`^(?:${source})$`, "su");
+    cache.set(source, re);
+  }
+  return re;
+}
+
+const escape = (c: string) => c.replace(/[\\^$.|+()[\]{}]/g, "\\$&");
+
+/**
+ * Glob match of the whole `text`. Path mode (`path: true`): `*` and `?` stop at "/", `**` crosses
+ * it, `**​/` also matches no folder, and a trailing `/**` also matches the folder itself
+ * ("exports/**" covers "exports"). In an allow entry no wildcard matches a name that starts with
+ * "." (".env", ".git/"): dot files are allowed only when the pattern names the dot itself
+ * (".config/**", "**​/.env"). A deny entry (`deny: true`) covers them too ("private/**" keeps
+ * "private/.env" out). Otherwise `*` and `**` match anything (plain values such as a filesystem
+ * base; URLs use urlMatch). No other syntax: every other character is literal. Case-sensitive;
+ * scopePermits folds case for case-insensitive volumes.
+ */
+export function globMatch(pattern: string, text: string, path: boolean, deny = false): boolean {
+  return compiled(globSource(pattern, path, deny)).test(text);
+}
+
+export function globSource(pattern: string, path: boolean, deny = false): string {
+  
+  const dots = !path || deny;
+  const guard = dots ? "" : "(?!\\.)";
+  const segment = `${guard}[^/]*`;
+  const across = dots ? ".*" : "(?:[^/]|/(?!\\.))*";
+  let out = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i]!;
+    const start = i === 0 || pattern[i - 1] === "/";
+    if (c === "*") {
+      const double = pattern[i + 1] === "*";
+      if (!double) {
+        out += path ? (start ? segment : "[^/]*") : ".*";
+        continue;
+      }
+      i++;
+      if (!path) out += ".*";
+      else if (pattern[i + 1] === "/" && start) {
+        out += `(?:${segment}/)*`; 
+        i++;
+      } else if (i === pattern.length - 1 && pattern[i - 2] === "/") {
+        out = `${out.slice(0, -1)}(?:/${segment})*`; 
+      } else out += (start ? guard : "") + across;
+    } else if (c === "?") out += path ? (start ? `${guard}[^/]` : "[^/]") : ".";
+    else out += escape(c);
+  }
+  return out;
+}
+
+/** `*` (and `**`) → `star`, `?` → one character, everything else literal. */
+function wildcard(pattern: string, text: string, star: string): boolean {
+  let out = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i]!;
+    if (c === "*") {
+      while (pattern[i + 1] === "*") i++;
+      out += star;
+    } else out += c === "?" ? "." : escape(c);
+  }
+  return compiled(out).test(text);
+}
+
+/**
+ * A URL split for matching. `rest` is the path of a URL with an authority, or what follows the
+ * scheme otherwise (the addresses of mailto:, the number of tel:). Scheme and host are lowercase.
+ * A URL's query and fragment are not part of it; in a pattern `?` is a wildcard, so only "/" ends
+ * the authority.
+ */
+export interface UrlParts {
+  scheme: string;
+  host: string | null;
+  port: string;
+  rest: string;
+}
+
+export function urlParts(text: string, pattern = false): UrlParts | null {
+  const colon = text.indexOf(":");
+  if (colon <= 0) return null;
+  const scheme = text.slice(0, colon).toLowerCase();
+  let rest = text.slice(colon + 1);
+  const query = pattern ? -1 : rest.search(/[?#]/);
+  if (query >= 0) rest = rest.slice(0, query);
+  if (!rest.startsWith("//")) return { scheme, host: null, port: "", rest };
+  rest = rest.slice(2);
+  const end = rest.indexOf("/");
+  let authority = end < 0 ? rest : rest.slice(0, end);
+  authority = authority.slice(authority.lastIndexOf("@") + 1); 
+  const bracket = authority.startsWith("[") ? authority.indexOf("]") + 1 : 0; 
+  const portColon = authority.indexOf(":", bracket);
+  return {
+    scheme,
+    host: (portColon < 0 ? authority : authority.slice(0, portColon)).toLowerCase(),
+    port: portColon < 0 ? "" : authority.slice(portColon + 1),
+    rest: end < 0 ? "" : rest.slice(end),
+  };
+}
+
+const DEFAULT_PORTS: Record<string, string> = { http: "80", https: "443", ws: "80", wss: "443" };
+
+/**
+ * URL scope match, for the fields a plugin names in scopePermits' `urlFields`: scheme, host, port
+ * and the rest are compared separately, so no wildcard reaches from one into another
+ * ("https://*.example.com/*" never matches "https://evil.com/x.example.com/"). Scheme and host
+ * ignore case, and `*` in the host spans dots (a.b.example.com). A pattern without a port matches
+ * only the scheme's default port in an allow entry ("https://api.example.com/*" does not reach a
+ * debug server on :8443, as URLPattern strings in Tauri do), but every port in a deny entry (a deny
+ * of a host covers all of it); ":*" is any port. A pattern without a path matches any path, and `*`
+ * alone every URL; `*` in the path crosses "/". The query and fragment are never compared, and `?`
+ * is always a one-character wildcard. A pattern without a scheme matches nothing. `url` is the
+ * plugin's normalized URL (percent-encoded, no default port, dot segments resolved).
+ */
+export function urlMatch(pattern: string, url: string, deny = false): boolean {
+  if (/^\*+$/.test(pattern)) return true;
+  const p = urlParts(pattern, true);
+  const v = urlParts(url);
+  if (!p || !v || (p.host === null) !== (v.host === null)) return false;
+  if (!wildcard(p.scheme, v.scheme, "[a-z0-9+.-]*")) return false;
+  if (p.host !== null) {
+    if (!wildcard(p.host, v.host!, ".*")) return false;
+    const port = v.port || DEFAULT_PORTS[v.scheme] || "";
+    if (p.port === "" ? !deny && port !== (DEFAULT_PORTS[v.scheme] ?? "") : p.port !== "*" && p.port !== port)
+      return false;
+    if (p.rest === "") return true;
+  }
+  return wildcard(p.rest, v.rest, ".*");
+}
+
+function entryMatches(
+  entry: ScopeEntry,
+  value: Record<string, string>,
+  pathFields: readonly string[],
+  urlFields: readonly string[],
+  deny: boolean,
+  fold: boolean,
+): boolean {
+  for (const [field, pattern] of Object.entries(entry)) {
+    const actual = value[field];
+    if (actual === undefined) return false;
+    const path = pathFields.includes(field);
+    const match = urlFields.includes(field)
+      ? urlMatch(pattern, actual, deny)
+      : path && fold
+        ? globMatch(pattern.toLowerCase(), actual.toLowerCase(), true, deny)
+        : globMatch(pattern, actual, path, deny);
+    if (!match) return false;
+  }
+  return true;
+}
+
+/**
+ * Whether `value` (the fields of what a call touches, e.g. { base, path } or { url }) is inside the
+ * call's scope: no deny entry matches, and some allow entry matches unless allow is unrestricted.
+ * `fold`: the path fields name files on a case-insensitive volume (macOS and Windows by default,
+ * Android's shared storage), so "Secret/x" is compared as "secret/x" and a deny cannot be passed
+ * by changing case.
+ */
+export function scopePermits(
+  scope: CallScope | undefined | null,
+  value: Record<string, string>,
+  pathFields: readonly string[] = [],
+  urlFields: readonly string[] = [],
+  fold = false,
+): boolean {
+  if (!scope) return true;
+  if (scope.deny.some((e) => entryMatches(e, value, pathFields, urlFields, true, fold))) return false;
+  return scope.allow === null || scope.allow.some((e) => entryMatches(e, value, pathFields, urlFields, false, fold));
+}

package/vendor/@akanjs/native/packages/core/src/boot.ts

@@ -0,0 +1,97 @@
+
+
+import { loadAcl, type ResolvedAcl } from "./acl.ts";
+
+export type Platform = "web" | "macos" | "windows" | "linux" | "ios" | "android";
+
+/**
+ * How a host provides a plugin:
+ * - "web": the plugin's web implementation runs inside the WebView
+ * - { methods, events }: the host has a native implementation of these
+ * A plugin missing from the map is unsupported on that host (web platform excepted).
+ */
+/**
+ * "web": the page runs the web implementation. An object: the host implements these methods and
+ * events; with `web: true` the others fall back to the web implementation (e.g. macOS camera:
+ * native permission state, getUserMedia capture).
+ */
+/**
+ * `coalesce`: events whose payload is a snapshot (progress, sizes, positions): the host sends only the
+ * latest of a burst (architecture review stage 4, `coalesce: "latest"`).
+ */
+export type PluginDecl = "web" | { methods: string[]; events: string[]; web?: true; coalesce?: string[] };
+
+export interface AppInfo {
+  id: string;
+  name: string;
+  version: string;
+  build?: number;
+}
+
+export interface AkanNativeBoot {
+  v: 1;
+  platform: Platform;
+  runtimeVersion: string;
+  dev: boolean;
+  app: AppInfo | null;
+  env: Record<string, string>;
+  plugins: Record<string, PluginDecl>;
+  /** Desktop: this page's window (1 = the window the app opened, SH-6). Absent elsewhere. */
+  windowId?: number;
+  /** The resolved capabilities (PL-11). The host enforces them; the page applies them to web implementations. */
+  acl?: ResolvedAcl;
+  /** Native hosts: fingerprint of what the binary provides natively; web bundles must match it (UP-3). */
+  nativeApi?: string;
+  /** Native hosts: bridge v1.1 features (protocol.ts BRIDGE_FEATURES). */
+  bridge?: { features: string[] };
+  /** The app's origin, set by the shell (the web: the page's): the one value origin checks use. */
+  origin?: string;
+  /** Native hosts: the page's engine (wkwebview, webview2, webkitgtk, android-webview) and its version. */
+  engine?: string;
+  engineVersion?: string;
+}
+
+/** The global object. init.js fills the boot fields, @akanjs/native/core adds `receive`. */
+export interface AkanNativeGlobal extends Partial<AkanNativeBoot> {
+  /** Entry point for host → JS messages (responses on Android, events everywhere). */
+  receive?: (message: unknown) => void;
+  /** Shared runtime state, so that duplicated copies of @akanjs/native/core in one page agree. */
+  __runtime?: unknown;
+}
+
+const PLATFORMS: readonly Platform[] = ["web", "macos", "windows", "linux", "ios", "android"];
+
+export function akanNativeGlobal(): AkanNativeGlobal {
+  const g = globalThis as { __AKAN_NATIVE__?: AkanNativeGlobal };
+  g.__AKAN_NATIVE__ ??= {};
+  return g.__AKAN_NATIVE__;
+}
+
+/**
+ * Reads the boot data. Without init.js (plain dev server, unit tests) the page
+ * behaves as the web platform with an empty env.
+ */
+export function readBoot(): AkanNativeBoot {
+  const g = akanNativeGlobal();
+  const acl = loadAcl(g).acl;
+  return {
+    v: 1,
+    platform: g.platform && PLATFORMS.includes(g.platform) ? g.platform : "web",
+    runtimeVersion: typeof g.runtimeVersion === "string" ? g.runtimeVersion : "0.0.0",
+    dev: g.dev === true,
+    app: g.app ?? null,
+    env: Object.freeze({ ...(g.env ?? {}) }),
+    plugins: g.plugins ?? {},
+    ...(typeof g.windowId === "number" ? { windowId: g.windowId } : {}),
+    
+    ...(acl ? { acl } : {}),
+    ...(typeof g.nativeApi === "string" ? { nativeApi: g.nativeApi } : {}),
+    ...(typeof g.origin === "string"
+      ? { origin: g.origin }
+      : typeof location !== "undefined" && location.origin !== "null"
+        ? { origin: location.origin }
+        : {}),
+    ...(typeof g.engine === "string" ? { engine: g.engine } : {}),
+    ...(typeof g.engineVersion === "string" ? { engineVersion: g.engineVersion } : {}),
+  };
+}

package/vendor/@akanjs/native/packages/core/src/contract.ts

@@ -0,0 +1,100 @@
+
+
+export const ERROR_CODES = ["UNSUPPORTED", "PERMISSION_DENIED", "CANCELLED", "TIMEOUT", "INVALID_ARGS", "NOT_FOUND", "NOT_ALLOWED", "INTERNAL"] as const;
+
+/** File name extension → MIME type (assets and FileRefs). */
+export const MIME: Readonly<Record<string, string>> = {
+  html: "text/html",
+  htm: "text/html",
+  js: "text/javascript",
+  mjs: "text/javascript",
+  css: "text/css",
+  json: "application/json",
+  map: "application/json",
+  webmanifest: "application/manifest+json",
+  txt: "text/plain",
+  text: "text/plain",
+  log: "text/plain",
+  md: "text/markdown",
+  csv: "text/csv",
+  tsv: "text/tab-separated-values",
+  xml: "application/xml",
+  yaml: "application/yaml",
+  yml: "application/yaml",
+  ics: "text/calendar",
+  vcf: "text/vcard",
+  pdf: "application/pdf",
+  rtf: "application/rtf",
+  zip: "application/zip",
+  gz: "application/gzip",
+  tar: "application/x-tar",
+  wasm: "application/wasm",
+  epub: "application/epub+zip",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  heic: "image/heic",
+  heif: "image/heif",
+  bmp: "image/bmp",
+  svg: "image/svg+xml",
+  ico: "image/x-icon",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  mp3: "audio/mpeg",
+  m4a: "audio/mp4",
+  aac: "audio/aac",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  flac: "audio/flac",
+  mp4: "video/mp4",
+  m4v: "video/mp4",
+  mov: "video/quicktime",
+  webm: "video/webm",
+  ttf: "font/ttf",
+  otf: "font/otf",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  glb: "model/gltf-binary",
+  gltf: "model/gltf+json",
+};
+
+/** Besides text/*, the asset types served with charset=utf-8. */
+export const MIME_UTF8: readonly string[] = ["application/json", "application/manifest+json", "application/xml", "application/yaml", "image/svg+xml", "model/gltf+json"];
+
+/** An id grammar: allowed characters, length, and an optional extension after the first dot. */
+export interface IdSpec {
+  chars: string;
+  first: string;
+  notFirst: string;
+  min: number;
+  max: number;
+  extChars: string;
+  extMax: number;
+}
+
+export const ID_FILE_REF: IdSpec = { chars: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-", first: "", notFirst: "", min: 1, max: 128, extChars: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789", extMax: 8 };
+export const ID_BUNDLE: IdSpec = { chars: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.-", first: "", notFirst: ".", min: 1, max: 80, extChars: "", extMax: 0 };
+export const ID_DOCUMENT: IdSpec = { chars: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-", first: "", notFirst: "", min: 8, max: 64, extChars: "", extMax: 0 };
+export const ID_NAME: IdSpec = { chars: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.-", first: "$ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz", notFirst: "", min: 1, max: 64, extChars: "", extMax: 0 };
+
+export const EXTERNAL_SCHEMES: readonly string[] = ["http", "https", "mailto", "tel"];
+export const FRAME_SCHEMES: readonly string[] = ["http", "https", "data", "blob", "about"];
+/** Schemes an app can never add to the external list. */
+export const NEVER_EXTERNAL_SCHEMES: readonly string[] = ["javascript", "vbscript", "file", "data", "blob", "about", "content", "intent", "app"];
+
+export const ROUTES = { root: "__akan_native", init: "init.js", ipc: "ipc", hello: "hello", file: "file" } as const;
+
+export const INIT_PREFIX = "window.__AKAN_NATIVE__=(function(o,b,e){for(var k in b)o[k]=b[k];o.env=e;return o})(window.__AKAN_NATIVE__||{},";
+export const INIT_SUFFIX = ");\n";
+export const MAX_RANGE_BYTES = 1024000;
+export const EXTERNAL_OPENS_PER_SECOND = 1;
+export const MAX_RETAINED_EVENTS = 16;

package/vendor/@akanjs/native/packages/core/src/errors.ts

@@ -0,0 +1,95 @@
+import { type BridgeErrorBody, ERROR_CODES, type ErrorCode } from "./protocol.ts";
+
+/**
+ * The web-standard name of each code (bridge v1.1), so `error.name === "AbortError"` works as it does
+ * for fetch; `code` stays the akan-native code.
+ */
+const ERROR_NAMES: Partial<Record<ErrorCode, string>> = {
+  CANCELLED: "AbortError",
+  TIMEOUT: "TimeoutError",
+  PERMISSION_DENIED: "NotAllowedError",
+  NOT_ALLOWED: "NotAllowedError",
+  UNSUPPORTED: "NotSupportedError",
+  NOT_FOUND: "NotFoundError",
+};
+
+export interface AkanNativeErrorOptions {
+  cause?: unknown;
+  /** Details a caller can act on, e.g. `{ reason: "packageManaged" }`. */
+  data?: unknown;
+  /** The same call may work later. */
+  retryable?: boolean;
+  /** Overrides the name derived from the code (DataCloneError for arguments JSON cannot carry). */
+  name?: string;
+}
+
+export class AkanNativeError extends Error {
+  readonly code: ErrorCode;
+  readonly data?: unknown;
+  readonly retryable: boolean;
+
+  constructor(code: ErrorCode, message: string, options?: AkanNativeErrorOptions) {
+    super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+    this.name = options?.name ?? ERROR_NAMES[code] ?? "AkanNativeError";
+    this.code = code;
+    if (options?.data !== undefined) this.data = options.data;
+    this.retryable = options?.retryable === true;
+  }
+
+  /**
+   * Builds a real Error from a wire error so callers get a stack trace
+   * (Capacitor copies native error fields onto an Error for the same reason:
+   * capacitor/core/native-bridge.ts `returnResult`).
+   */
+  static fromBody(body: BridgeErrorBody | undefined, cause?: unknown): AkanNativeError {
+    const code = body && ERROR_CODES.includes(body.code) ? body.code : "INTERNAL";
+    return new AkanNativeError(code, body?.message ?? "unknown error", {
+      data: body?.data,
+      retryable: body?.retryable === true,
+      cause,
+    });
+  }
+
+  /** Normalizes anything thrown by an implementation into an AkanNativeError. */
+  static from(error: unknown): AkanNativeError {
+    if (error instanceof AkanNativeError) return error;
+    if (error instanceof Error || isDomException(error)) {
+      const e = error as Error;
+      const code = FROM_NAMES[e.name];
+      return new AkanNativeError(code ?? "INTERNAL", e.message, { cause: error });
+    }
+    return new AkanNativeError("INTERNAL", String(error));
+  }
+
+  /** The error body a host sends for this error. */
+  toBody(): BridgeErrorBody {
+    const body: BridgeErrorBody = { code: this.code, message: this.message };
+    if (this.data !== undefined) body.data = this.data;
+    if (this.retryable) body.retryable = true;
+    return body;
+  }
+}
+
+/** Web errors thrown by web implementations and the page's own signals. */
+const FROM_NAMES: Record<string, ErrorCode> = {
+  AbortError: "CANCELLED",
+  TimeoutError: "TIMEOUT",
+  NotAllowedError: "PERMISSION_DENIED",
+  SecurityError: "PERMISSION_DENIED",
+  NotSupportedError: "UNSUPPORTED",
+  NotFoundError: "NOT_FOUND",
+};
+
+/** DOMException is not an Error subclass in every engine. */
+function isDomException(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { name?: unknown }).name === "string" &&
+    typeof (value as { message?: unknown }).message === "string"
+  );
+}
+
+export function isAkanNativeError(error: unknown, code?: ErrorCode): error is AkanNativeError {
+  return error instanceof AkanNativeError && (code === undefined || error.code === code);
+}

package/vendor/@akanjs/native/packages/core/src/files.ts

@@ -0,0 +1,105 @@
+
+
+import { AkanNativeError } from "./errors.ts";
+import { BRIDGE_PLUGIN, type FileRef, RELEASE } from "./protocol.ts";
+import { runtime } from "./runtime.ts";
+
+/**
+ * Stops serving a FileRef. FileRefs live for the app session (architecture review, 2026-09-26), so
+ * release the ones the page no longer shows: photos, picked files, downloads. The host forgets the
+ * URL and deletes akan-native's own copy of the file; files that belong to the user (a document served in
+ * place) stay. Holding the URL is the permission, as for any follow-up on what a call handed out.
+ * Resolves whether it was served. On the web, a blob: URL is revoked.
+ */
+export async function releaseFile(file: FileRef | string): Promise<boolean> {
+  const url = typeof file === "string" ? file : file?.url;
+  if (typeof url !== "string") throw new AkanNativeError("INVALID_ARGS", "releaseFile needs a FileRef or its url");
+  const rt = runtime();
+  if (!rt.transport) {
+    if (!url.startsWith("blob:")) return false;
+    URL.revokeObjectURL(url);
+    return true;
+  }
+  const response = await rt.transport.send({
+    v: 1,
+    id: ++rt.nextId,
+    plugin: BRIDGE_PLUGIN,
+    method: RELEASE,
+    args: { url },
+  });
+  if (!response.ok) throw AkanNativeError.fromBody(response.error);
+  return (response.result as { released?: unknown } | undefined)?.released === true;
+}
+
+export interface FileReadOptions {
+  /** Bytes per Range request. Default 4 MiB. */
+  chunkSize?: number;
+  signal?: AbortSignal;
+}
+
+const CONTENT_RANGE = /^bytes (\d+)-(\d+)\/(\d+|\*)$/;
+
+/**
+ * Reads a FileRef (or any same-origin URL) in pieces with HTTP Range requests, so a big file never
+ * has to be one response: the desktop shell answers without streaming (WRY), reading a whole
+ * response into memory (architecture review stage 4). Every host serves FileRefs with
+ * `Accept-Ranges: bytes`. A server that ignores Range (200) is streamed as it answers.
+ */
+export function fileStream(file: FileRef | string, options: FileReadOptions = {}): ReadableStream<Uint8Array> {
+  const url = typeof file === "string" ? file : file.url;
+  const chunk = Math.max(1, Math.floor(options.chunkSize ?? 4 << 20));
+  let offset = 0;
+  let total: number | null = typeof file === "object" && Number.isFinite(file.size) ? file.size : null;
+  let whole: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        if (whole) {
+          const { done, value } = await whole.read();
+          if (done) controller.close();
+          else controller.enqueue(value);
+          return;
+        }
+        if (total !== null && offset >= total) return controller.close();
+        const response = await fetch(url, {
+          headers: { range: `bytes=${offset}-${offset + chunk - 1}` },
+          ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (response.status === 416 && total === null) return controller.close(); 
+        if (response.status === 200) {
+          
+          whole = response.body!.getReader();
+          return this.pull!(controller);
+        }
+        if (response.status !== 206)
+          throw new AkanNativeError(
+            response.status === 404 ? "NOT_FOUND" : "INTERNAL",
+            `${url}: HTTP ${response.status}`,
+          );
+        const range = CONTENT_RANGE.exec(response.headers.get("content-range") ?? "");
+        if (range && range[3] !== "*") total = Number(range[3]);
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        offset += bytes.length;
+        if (bytes.length) controller.enqueue(bytes);
+        if (bytes.length === 0 || (total !== null && offset >= total)) controller.close();
+      } catch (error) {
+        controller.error(AkanNativeError.from(error));
+      }
+    },
+    cancel() {
+      void whole?.cancel();
+    },
+  });
+}
+
+/** A FileRef as a Blob, read in Range pieces (see fileStream); `type` is the FileRef's MIME type. */
+export async function fileBlob(file: FileRef | string, options: FileReadOptions = {}): Promise<Blob> {
+  const parts: Uint8Array[] = [];
+  const reader = fileStream(file, options).getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    parts.push(value);
+  }
+  return new Blob(parts as BlobPart[], typeof file === "object" && file.mime ? { type: file.mime } : {});
+}