@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/runtime/react/app-shell/toolcraft-source-asset-owner.test.ts

@@ -0,0 +1,194 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { acquireToolcraftSourceAssetOwner } from "./toolcraft-source-asset-owner";
+import {
+  createTestSourceAssetCoordinator,
+  createTestSourceAssetStore,
+} from "./toolcraft-source-asset-test-support";
+
+function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((resolvePromise) => {
+    resolve = resolvePromise;
+  });
+  return { promise, resolve };
+}
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("Toolcraft source asset owner", () => {
+  it("binds the resolver without relying on the proof decorator", async () => {
+    type ReceiverAwareCoordinator = ReturnType<
+      typeof createTestSourceAssetCoordinator
+    > & Readonly<{ resolverBytes: Uint8Array }>;
+
+    const resolverBytes = new Uint8Array([7, 8, 9]);
+    const coordinator: ReceiverAwareCoordinator = {
+      ...createTestSourceAssetCoordinator(),
+      resolverBytes,
+      resolveResource: vi.fn(async function (
+        this: ReceiverAwareCoordinator,
+      ) {
+        expect(this).toBe(coordinator);
+        return this.resolverBytes;
+      }),
+    };
+    const lease = acquireToolcraftSourceAssetOwner({
+      createCoordinator: () => coordinator,
+      store: createTestSourceAssetStore(),
+    });
+    expect(lease.coordinator).toBe(coordinator);
+    const resolveResource = lease.coordinator.resolveResource;
+    if (!resolveResource) throw new Error("Expected a resource resolver.");
+
+    await expect(resolveResource(
+      "media:image:production-receiver",
+      { signal: new AbortController().signal },
+    )).resolves.toBe(resolverBytes);
+    lease.release();
+  });
+
+  it("attempts every cleanup and reports their failures once", async () => {
+    const presentationFailure = new Error("presentation cleanup failed");
+    const coordinatorFailure = new Error("coordinator cleanup failed");
+    const releaseResourceRef = vi.fn(() => {
+      throw presentationFailure;
+    });
+    const disposeCoordinator = vi.fn(async () => {
+      throw coordinatorFailure;
+    });
+    const onError = vi.fn();
+    const store = createTestSourceAssetStore();
+    const lease = acquireToolcraftSourceAssetOwner({
+      createCoordinator: () => createTestSourceAssetCoordinator({
+        dispose: disposeCoordinator,
+        resolveResource: vi.fn(async () => new Uint8Array([1, 2, 3])),
+        retainResourceRef: () => releaseResourceRef,
+      }),
+      onError,
+      store,
+    });
+    const resources = lease.presentationResources;
+    if (!resources) throw new Error("Expected presentation resources.");
+    await resources.retain("media:image:cleanup", "image/png");
+
+    lease.release();
+
+    await vi.waitFor(() => expect(onError).toHaveBeenCalledTimes(1));
+    expect(releaseResourceRef).toHaveBeenCalledTimes(1);
+    expect(disposeCoordinator).toHaveBeenCalledTimes(1);
+    const reported = onError.mock.calls[0]?.[0];
+    expect(reported).toBeInstanceOf(AggregateError);
+    expect((reported as AggregateError).errors).toEqual([
+      presentationFailure,
+      coordinatorFailure,
+    ]);
+    expect(() => acquireToolcraftSourceAssetOwner({ store })).toThrow(
+      "Toolcraft source asset owner failed to dispose.",
+    );
+  });
+
+  it("keeps a disposing owner registered until cleanup settles", async () => {
+    const disposal = createDeferred<void>();
+    const store = createTestSourceAssetStore();
+    const firstCoordinator = createTestSourceAssetCoordinator({
+      dispose: vi.fn(() => disposal.promise),
+    });
+    const first = acquireToolcraftSourceAssetOwner({
+      createCoordinator: () => firstCoordinator,
+      store,
+    });
+
+    first.release();
+    first.release();
+    await Promise.resolve();
+
+    const createReplacement = vi.fn(() => createTestSourceAssetCoordinator());
+    expect(() => acquireToolcraftSourceAssetOwner({
+      createCoordinator: createReplacement,
+      store,
+    })).toThrow("Toolcraft source asset owner is disposing.");
+    expect(createReplacement).not.toHaveBeenCalled();
+
+    disposal.resolve(undefined);
+    await vi.waitFor(() =>
+      expect(firstCoordinator.dispose).toHaveBeenCalledTimes(1)
+    );
+    await Promise.resolve();
+    const replacement = acquireToolcraftSourceAssetOwner({
+      createCoordinator: createReplacement,
+      store,
+    });
+    expect(createReplacement).toHaveBeenCalledTimes(1);
+    replacement.release();
+  });
+
+  it("reuses the active store owner regardless of later construction inputs", () => {
+    const store = createTestSourceAssetStore();
+    const firstFactory = vi.fn(() => createTestSourceAssetCoordinator());
+    const replacementFactory = vi.fn(() => createTestSourceAssetCoordinator());
+    const firstReporter = vi.fn();
+    const replacementReporter = vi.fn();
+    const first = acquireToolcraftSourceAssetOwner({
+      createCoordinator: firstFactory,
+      onError: firstReporter,
+      store,
+    });
+    const second = acquireToolcraftSourceAssetOwner({
+      createCoordinator: replacementFactory,
+      onError: replacementReporter,
+      store,
+    });
+    const failure = new Error("existing owner operation failed");
+
+    expect(second.coordinator).toBe(first.coordinator);
+    expect(replacementFactory).not.toHaveBeenCalled();
+    second.reportError(failure);
+    expect(firstReporter).toHaveBeenCalledWith(failure);
+    expect(replacementReporter).not.toHaveBeenCalled();
+
+    second.release();
+    first.release();
+  });
+
+  it("reports operational failures through the contextual error channel", () => {
+    const failure = new Error("model hydration failed");
+    const onError = vi.fn();
+    const lease = acquireToolcraftSourceAssetOwner({
+      createCoordinator: () => createTestSourceAssetCoordinator(),
+      onError,
+      store: createTestSourceAssetStore(),
+    });
+
+    lease.reportError(failure);
+
+    expect(onError).toHaveBeenCalledWith(failure);
+    lease.release();
+  });
+
+  it("preserves cleanup and contextual reporter failures", async () => {
+    const cleanupFailure = new Error("cleanup failed");
+    const reporterFailure = new Error("reporter failed");
+    const reportError = vi.fn();
+    vi.stubGlobal("reportError", reportError);
+    const lease = acquireToolcraftSourceAssetOwner({
+      createCoordinator: () => createTestSourceAssetCoordinator({
+        dispose: vi.fn(async () => Promise.reject(cleanupFailure)),
+      }),
+      onError: () => {
+        throw reporterFailure;
+      },
+      store: createTestSourceAssetStore(),
+    });
+
+    lease.release();
+
+    await vi.waitFor(() => expect(reportError).toHaveBeenCalledTimes(1));
+    const reported = reportError.mock.calls[0]?.[0];
+    expect(reported).toBeInstanceOf(AggregateError);
+    expect((reported as AggregateError).errors).toEqual([
+      cleanupFailure,
+      reporterFailure,
+    ]);
+  });
+});

package/templates/runtime/react/app-shell/toolcraft-source-asset-owner.ts

@@ -0,0 +1,227 @@
+import type { ToolcraftBinaryAssetRepository } from "../../source-assets/repository/binary-asset-repository";
+import { createIndexedDbToolcraftBinaryAssetRepository } from "../../source-assets/repository/indexeddb-binary-asset-repository";
+import { createMemoryToolcraftBinaryAssetRepository } from "../../source-assets/repository/memory-binary-asset-repository";
+import { createUnavailableToolcraftBinaryAssetRepository } from "../../source-assets/repository/unavailable-binary-asset-repository";
+import {
+  createToolcraftSourceAssetCoordinator,
+  type ToolcraftSourceAssetCoordinator,
+} from "../../source-assets/source-asset-coordinator";
+import {
+  createToolcraftSourceAssetPresentationResources,
+  type ToolcraftSourceAssetPresentationResources,
+} from "../../source-assets/source-asset-presentation-resources";
+import type { ToolcraftExternalStore } from "../../state/toolcraft-external-store";
+
+type ToolcraftSourceAssetCoordinatorFactory = (
+  store: ToolcraftExternalStore,
+) => ToolcraftSourceAssetCoordinator;
+
+type ToolcraftSourceAssetCoordinatorDecorator = (
+  coordinator: ToolcraftSourceAssetCoordinator,
+  store: ToolcraftExternalStore,
+) => ToolcraftSourceAssetCoordinator;
+
+type ToolcraftSourceAssetOwner = {
+  coordinator: ToolcraftSourceAssetCoordinator;
+  leases: number;
+  lifecycle: "active" | "disposing" | "failed";
+  lifecycleGeneration: number;
+  onError: (error: unknown) => void;
+  presentationResources: ToolcraftSourceAssetPresentationResources | null;
+  store: ToolcraftExternalStore;
+};
+
+type ToolcraftSourceAssetOwnerLease = Readonly<{
+  coordinator: ToolcraftSourceAssetCoordinator;
+  presentationResources: ToolcraftSourceAssetPresentationResources | null;
+  release: () => void;
+  reportError: (error: unknown) => void;
+}>;
+
+const sourceAssetOwners = new WeakMap<
+  ToolcraftExternalStore,
+  ToolcraftSourceAssetOwner
+>();
+
+function createRepository(): ToolcraftBinaryAssetRepository {
+  if (typeof globalThis.indexedDB === "undefined") {
+    return typeof navigator !== "undefined" &&
+      navigator.userAgent.toLowerCase().includes("jsdom")
+      ? createMemoryToolcraftBinaryAssetRepository()
+      : createUnavailableToolcraftBinaryAssetRepository();
+  }
+
+  try {
+    return createIndexedDbToolcraftBinaryAssetRepository();
+  } catch {
+    return createUnavailableToolcraftBinaryAssetRepository();
+  }
+}
+
+function createDefaultCoordinator(
+  store: ToolcraftExternalStore,
+): ToolcraftSourceAssetCoordinator {
+  return createToolcraftSourceAssetCoordinator({
+    dispatch: store.dispatch,
+    getState: store.getCommittedState,
+    repository: createRepository(),
+  });
+}
+
+function reportSourceAssetOwnerError(error: unknown): void {
+  const globalReportError = globalThis.reportError;
+  if (typeof globalReportError === "function") {
+    try {
+      globalReportError(error);
+      return;
+    } catch (reportingFailure) {
+      console.error(
+        "Toolcraft source asset owner error reporting failed.",
+        new AggregateError(
+          [error, reportingFailure],
+          "Toolcraft source asset owner operation and reporting both failed.",
+        ),
+      );
+      return;
+    }
+  }
+  console.error("Toolcraft source asset owner operation failed.", error);
+}
+
+function reportOwnerError(
+  owner: ToolcraftSourceAssetOwner,
+  error: unknown,
+): void {
+  try {
+    owner.onError(error);
+  } catch (reportingFailure) {
+    reportSourceAssetOwnerError(
+      new AggregateError(
+        [error, reportingFailure],
+        "Toolcraft source asset owner operation and its injected reporter both failed.",
+      ),
+    );
+  }
+}
+
+function createOwner(
+  store: ToolcraftExternalStore,
+  createCoordinator: ToolcraftSourceAssetCoordinatorFactory,
+  decorateCoordinator: ToolcraftSourceAssetCoordinatorDecorator | undefined,
+  onError: (error: unknown) => void,
+): ToolcraftSourceAssetOwner {
+  const baseCoordinator = createCoordinator(store);
+  const resolveResource = baseCoordinator.resolveResource;
+  if (resolveResource) {
+    baseCoordinator.resolveResource = resolveResource.bind(baseCoordinator);
+  }
+  const coordinator = decorateCoordinator
+    ? decorateCoordinator(baseCoordinator, store)
+    : baseCoordinator;
+  const presentationResources =
+    coordinator.resolveResource && coordinator.retainResourceRef
+      ? createToolcraftSourceAssetPresentationResources({
+          resolveResource: coordinator.resolveResource,
+          retainResourceRef: coordinator.retainResourceRef,
+        })
+      : null;
+  return {
+    coordinator,
+    leases: 0,
+    lifecycle: "active",
+    lifecycleGeneration: 0,
+    onError,
+    presentationResources,
+    store,
+  };
+}
+
+async function disposeOwner(owner: ToolcraftSourceAssetOwner): Promise<void> {
+  const failures: unknown[] = [];
+  try {
+    owner.presentationResources?.dispose();
+  } catch (error) {
+    failures.push(error);
+  }
+  try {
+    await owner.coordinator.dispose.call(owner.coordinator);
+  } catch (error) {
+    failures.push(error);
+  }
+
+  if (failures.length === 1) {
+    owner.lifecycle = "failed";
+    reportOwnerError(owner, failures[0]);
+  } else if (failures.length > 1) {
+    owner.lifecycle = "failed";
+    reportOwnerError(
+      owner,
+      new AggregateError(
+        failures,
+        "Toolcraft source asset owner failed to dispose all owned resources.",
+      ),
+    );
+  } else if (sourceAssetOwners.get(owner.store) === owner) {
+    sourceAssetOwners.delete(owner.store);
+  }
+}
+
+function scheduleOwnerDisposal(owner: ToolcraftSourceAssetOwner): void {
+  const lifecycleGeneration = ++owner.lifecycleGeneration;
+  queueMicrotask(() => {
+    if (
+      owner.lifecycle !== "active" ||
+      owner.leases !== 0 ||
+      owner.lifecycleGeneration !== lifecycleGeneration ||
+      sourceAssetOwners.get(owner.store) !== owner
+    ) {
+      return;
+    }
+    owner.lifecycle = "disposing";
+    void disposeOwner(owner);
+  });
+}
+
+export function acquireToolcraftSourceAssetOwner({
+  createCoordinator = createDefaultCoordinator,
+  decorateCoordinator,
+  onError = reportSourceAssetOwnerError,
+  store,
+}: Readonly<{
+  createCoordinator?: ToolcraftSourceAssetCoordinatorFactory;
+  decorateCoordinator?: ToolcraftSourceAssetCoordinatorDecorator;
+  onError?: (error: unknown) => void;
+  store: ToolcraftExternalStore;
+}>): ToolcraftSourceAssetOwnerLease {
+  let owner = sourceAssetOwners.get(store);
+  if (owner?.lifecycle === "disposing") {
+    throw new Error("Toolcraft source asset owner is disposing.");
+  }
+  if (owner?.lifecycle === "failed") {
+    throw new Error("Toolcraft source asset owner failed to dispose.");
+  }
+  if (!owner) {
+    owner = createOwner(
+      store,
+      createCoordinator,
+      decorateCoordinator,
+      onError,
+    );
+    sourceAssetOwners.set(store, owner);
+  }
+
+  owner.leases += 1;
+  owner.lifecycleGeneration += 1;
+  let released = false;
+  return Object.freeze({
+    coordinator: owner.coordinator,
+    presentationResources: owner.presentationResources,
+    release: () => {
+      if (released) return;
+      released = true;
+      owner.leases -= 1;
+      if (owner.leases === 0) scheduleOwnerDisposal(owner);
+    },
+    reportError: (error: unknown) => reportOwnerError(owner, error),
+  });
+}

package/templates/runtime/react/app-shell/toolcraft-source-asset-provider-ownership.test.tsx

@@ -0,0 +1,243 @@
+import * as React from "react";
+import { cleanup, render, waitFor } from "@testing-library/react";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { ToolcraftSourceAssetCoordinator } from "../../source-assets/source-asset-coordinator";
+import { ToolcraftSourceAssetProvider } from "./toolcraft-source-asset-context";
+import {
+  ToolcraftSourceAssetCoordinatorProbe as CoordinatorProbe,
+  createTestSourceAssetCoordinator as createTestCoordinator,
+  createTestSourceAssetStore as createTestStore,
+} from "./toolcraft-source-asset-test-support";
+
+afterEach(cleanup);
+
+function createDeferred<T>() {
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((_resolve, rejectPromise) => {
+    reject = rejectPromise;
+  });
+  return { promise, reject };
+}
+
+describe("Toolcraft source asset provider ownership", () => {
+  it("does not acquire or cache an owner for an uncommitted render", () => {
+    const store = createTestStore();
+    const coordinator = createTestCoordinator();
+    const createCoordinator = vi.fn(() => coordinator);
+
+    expect(renderToString(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={createCoordinator}
+        store={store}
+      >
+        <span>Server probe</span>
+      </ToolcraftSourceAssetProvider>,
+    )).toBe("");
+    expect(createCoordinator).not.toHaveBeenCalled();
+
+    const rendered = render(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={createCoordinator}
+        store={store}
+      >
+        <span data-testid="committed-source-asset-child" />
+      </ToolcraftSourceAssetProvider>,
+    );
+
+    expect(rendered.getByTestId("committed-source-asset-child")).toBeDefined();
+    expect(createCoordinator).toHaveBeenCalledTimes(1);
+  });
+
+  it("preserves the injected coordinator receiver through the provider", async () => {
+    type ReceiverAwareCoordinator = ToolcraftSourceAssetCoordinator & {
+      resolverBytes: Uint8Array;
+    };
+
+    const resolverBytes = new Uint8Array([4, 5, 6]);
+    const coordinator: ReceiverAwareCoordinator = {
+      ...createTestCoordinator(),
+      resolverBytes,
+      resolveResource: vi.fn(async function (
+        this: ReceiverAwareCoordinator,
+      ) {
+        expect(this).toBe(coordinator);
+        return this.resolverBytes;
+      }),
+    };
+    const observed: ToolcraftSourceAssetCoordinator[] = [];
+    render(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={() => coordinator}
+        store={createTestStore()}
+      >
+        <CoordinatorProbe capture={(value) => observed.push(value)} />
+      </ToolcraftSourceAssetProvider>,
+    );
+    const resolveResource = observed[0]?.resolveResource;
+    if (!resolveResource) throw new Error("Expected a resource resolver.");
+
+    await expect(resolveResource(
+      "media:image:receiver-aware",
+      { signal: new AbortController().signal },
+    )).resolves.toBe(resolverBytes);
+  });
+
+  it("reports hydration failures through the contextual owner channel", async () => {
+    const failure = new Error("model hydration failed");
+    const onError = vi.fn();
+    const coordinator = createTestCoordinator({
+      hydrateModels: vi.fn(async () => Promise.reject(failure)),
+    });
+    const rendered = render(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={() => coordinator}
+        onError={onError}
+        store={createTestStore()}
+      >
+        <span />
+      </ToolcraftSourceAssetProvider>,
+    );
+
+    await waitFor(() => expect(onError).toHaveBeenCalledWith(failure));
+    rendered.unmount();
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps same-store construction inputs stable across prop identity changes", async () => {
+    const store = createTestStore();
+    const firstReporter = vi.fn();
+    const replacementReporter = vi.fn();
+    const hydration = createDeferred<void>();
+    const hydrationFailure = new Error("original owner hydration failed");
+    const coordinator = createTestCoordinator({
+      hydrateModels: vi.fn(() => hydration.promise),
+    });
+    const observed: ToolcraftSourceAssetCoordinator[] = [];
+    const firstFactory = vi.fn(() => coordinator);
+    const replacementFactory = vi.fn(() => createTestCoordinator());
+    const rendered = render(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={firstFactory}
+        onError={firstReporter}
+        store={store}
+      >
+        <CoordinatorProbe capture={(value) => observed.push(value)} />
+        <span data-testid="stable-source-asset-child" />
+      </ToolcraftSourceAssetProvider>,
+    );
+
+    rendered.rerender(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={replacementFactory}
+        onError={replacementReporter}
+        store={store}
+      >
+        <CoordinatorProbe capture={(value) => observed.push(value)} />
+        <span data-testid="stable-source-asset-child" />
+      </ToolcraftSourceAssetProvider>,
+    );
+
+    expect(rendered.getByTestId("stable-source-asset-child")).toBeDefined();
+    expect(observed.length).toBeGreaterThan(0);
+    expect(observed.every((value) => value === coordinator)).toBe(true);
+    expect(firstFactory).toHaveBeenCalledTimes(1);
+    expect(replacementFactory).not.toHaveBeenCalled();
+    hydration.reject(hydrationFailure);
+    await waitFor(() => expect(firstReporter).toHaveBeenCalledWith(
+      hydrationFailure,
+    ));
+    expect(replacementReporter).not.toHaveBeenCalled();
+  });
+
+  it("uses current construction inputs when the store changes", async () => {
+    const firstStore = createTestStore();
+    const secondStore = createTestStore();
+    const firstReporter = vi.fn();
+    const secondReporter = vi.fn();
+    const secondFailure = new Error("second store hydration failed");
+    const firstCoordinator = createTestCoordinator();
+    const secondCoordinator = createTestCoordinator({
+      hydrateModels: vi.fn(async () => Promise.reject(secondFailure)),
+    });
+    const firstFactory = vi.fn(() => firstCoordinator);
+    const secondFactory = vi.fn(() => secondCoordinator);
+    const rendered = render(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={firstFactory}
+        onError={firstReporter}
+        store={firstStore}
+      >
+        <span data-testid="switched-source-asset-child" />
+      </ToolcraftSourceAssetProvider>,
+    );
+
+    rendered.rerender(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={secondFactory}
+        onError={secondReporter}
+        store={secondStore}
+      >
+        <span data-testid="switched-source-asset-child" />
+      </ToolcraftSourceAssetProvider>,
+    );
+
+    await waitFor(() => expect(secondReporter).toHaveBeenCalledWith(
+      secondFailure,
+    ));
+    expect(rendered.getByTestId("switched-source-asset-child")).toBeDefined();
+    expect(firstFactory).toHaveBeenCalledWith(firstStore);
+    expect(secondFactory).toHaveBeenCalledWith(secondStore);
+    expect(firstReporter).not.toHaveBeenCalledWith(secondFailure);
+  });
+
+  it("supports the deprecated error reporter alias for all owner failures", async () => {
+    const operationalFailure = new Error("model hydration failed through alias");
+    const disposalFailure = new Error("owner disposal failed through alias");
+    const onDisposeError = vi.fn();
+    const coordinator = createTestCoordinator({
+      dispose: vi.fn(async () => Promise.reject(disposalFailure)),
+      hydrateModels: vi.fn(async () => Promise.reject(operationalFailure)),
+    });
+    const rendered = render(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={() => coordinator}
+        onDisposeError={onDisposeError}
+        store={createTestStore()}
+      >
+        <span />
+      </ToolcraftSourceAssetProvider>,
+    );
+
+    await waitFor(() => expect(onDisposeError).toHaveBeenCalledWith(
+      operationalFailure,
+    ));
+    rendered.unmount();
+    await waitFor(() => expect(onDisposeError).toHaveBeenCalledWith(
+      disposalFailure,
+    ));
+  });
+
+  it("prefers onError over the deprecated reporter alias", async () => {
+    const failure = new Error("primary reporter failure");
+    const onError = vi.fn();
+    const onDisposeError = vi.fn();
+    const rendered = render(
+      <ToolcraftSourceAssetProvider
+        createCoordinator={() => createTestCoordinator({
+          hydrateModels: vi.fn(async () => Promise.reject(failure)),
+        })}
+        onDisposeError={onDisposeError}
+        onError={onError}
+        store={createTestStore()}
+      >
+        <span />
+      </ToolcraftSourceAssetProvider>,
+    );
+
+    await waitFor(() => expect(onError).toHaveBeenCalledWith(failure));
+    expect(onDisposeError).not.toHaveBeenCalled();
+    rendered.unmount();
+  });
+});