@vivix-labs/material-library 0.0.0-stage → 1.0.0-beta

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import { MaterialConfig } from './shared.js';
+export { Config } from './shared.js';
+import { ClientContext } from 'vivix-studio/sdk/client';
+import 'vivix-studio/sdk/shared';
+
+declare function MaterialProperties({ record }: {
+    record: any;
+}): React.JSX.Element;
+
+declare const dependencies: (config: MaterialConfig) => string[];
+declare function activate(client: ClientContext<MaterialConfig>): void;
+
+export { MaterialProperties, activate as default, dependencies };

package/dist/client.js

@@ -0,0 +1,94 @@
+// packages/material-library/src/ui/panels.tsx
+import * as React from "react";
+function ImportToProject(props) {
+  const { form, setForm, projects, save } = props;
+  return /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("label", null, "Target project", /* @__PURE__ */ React.createElement(
+    "select",
+    {
+      value: form.targetProjectId,
+      onChange: (e) => setForm({ ...form, targetProjectId: e.target.value })
+    },
+    /* @__PURE__ */ React.createElement("option", { value: "" }, "Choose a project"),
+    projects.map((p) => /* @__PURE__ */ React.createElement("option", { key: p.objectId, value: p.objectId }, p.data.name))
+  )), /* @__PURE__ */ React.createElement(
+    "button",
+    {
+      className: "primary",
+      disabled: !form.targetProjectId,
+      onClick: () => void save("assets.importMaterial", {
+        ref: form.ref,
+        targetProjectId: form.targetProjectId
+      })
+    },
+    "Copy into project"
+  ));
+}
+
+// packages/material-library/src/client.tsx
+import * as React2 from "react";
+
+// packages/material-library/src/shared.ts
+import { z } from "vivix-studio/sdk/shared";
+var Config = z.discriminatedUnion("role", [
+  z.object({
+    role: z.literal("service"),
+    dataInstance: z.string().min(1).default("data"),
+    serviceInstance: z.string().min(1).default("library")
+  }).strict(),
+  z.object({
+    role: z.literal("client"),
+    serviceInstance: z.string().min(1).default("user:library")
+  }).strict()
+]);
+var materialFields = z.object({
+  name: z.string().trim().min(1).max(200),
+  kind: z.enum(["text", "image", "video", "audio", "file"]),
+  tags: z.array(z.string().trim().min(1).max(64)).max(50).transform((x) => [...new Set(x)]).default([]),
+  category: z.enum(["character", "scene", "style", "sound", "reference", "other"]).default("other"),
+  description: z.string().max(4e3).default(""),
+  origin: z.enum(["import", "collected"]),
+  sourceRef: z.object({ storeId: z.uuid(), objectId: z.uuid(), versionId: z.uuid() }).strict().nullable().default(null),
+  sourceLabel: z.object({
+    projectName: z.string(),
+    objectName: z.string(),
+    versionNumber: z.number().int().positive()
+  }).strict().nullable().default(null),
+  lifecycle: z.enum(["ready", "archived"]).default("ready"),
+  recommendedVersionId: z.uuid(),
+  licenseNote: z.string().max(4e3).default("")
+}).strict();
+var materialData = materialFields.refine(
+  (v) => v.origin !== "collected" || v.sourceRef !== null,
+  "Collected materials require a fixed source."
+);
+
+// packages/material-library/src/client.tsx
+function MaterialProperties({ record }) {
+  return /* @__PURE__ */ React2.createElement("dl", null, /* @__PURE__ */ React2.createElement("dt", null, "Category"), /* @__PURE__ */ React2.createElement("dd", null, record.data.category), /* @__PURE__ */ React2.createElement("dt", null, "Tags"), /* @__PURE__ */ React2.createElement("dd", null, record.data.tags.map((t) => /* @__PURE__ */ React2.createElement("span", { key: t, className: "tag" }, t))), /* @__PURE__ */ React2.createElement("dt", null, "Source"), /* @__PURE__ */ React2.createElement("dd", null, record.data.sourceLabel ? `${record.data.sourceLabel.projectName} / ${record.data.sourceLabel.objectName} / v${record.data.sourceLabel.versionNumber}` : record.data.origin), /* @__PURE__ */ React2.createElement("dt", null, "Recommended version"), /* @__PURE__ */ React2.createElement("dd", null, "v", record.versions?.find((v) => v.versionId === record.data.recommendedVersionId)?.versionNumber ?? "\u2014"), /* @__PURE__ */ React2.createElement("dt", null, "Uses"), /* @__PURE__ */ React2.createElement("dd", null, record.usageCount ?? "Query usage"), /* @__PURE__ */ React2.createElement("dt", null, "License"), /* @__PURE__ */ React2.createElement("dd", null, record.data.licenseNote || "Unspecified"));
+}
+var dependencies = (config) => config.role === "client" ? [config.serviceInstance] : [];
+function activate(client) {
+  client.provide({ serviceInstance: client.config.serviceInstance });
+  let active = true;
+  client.registerUI({
+    id: "library.import-form",
+    title: "Import material",
+    kind: "component",
+    component: (props) => active ? /* @__PURE__ */ React2.createElement(ImportToProject, { ...props }) : null
+  });
+  client.registerUI({
+    id: "library.properties",
+    title: "Material properties",
+    kind: "component",
+    component: (props) => active ? /* @__PURE__ */ React2.createElement(MaterialProperties, { ...props }) : null
+  });
+  client.onDispose(() => {
+    active = false;
+  });
+}
+export {
+  Config,
+  MaterialProperties,
+  activate as default,
+  dependencies
+};

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+import { ServerContext } from 'vivix-studio/sdk/server';
+import { z } from 'vivix-studio/sdk/shared';
+import { Config } from './shared.js';
+
+declare const dependencies: (config: z.infer<typeof Config>) => string[];
+declare function activate(ctx: ServerContext<z.infer<typeof Config>>): void;
+
+export { Config, activate as default, dependencies };

package/dist/server.js

@@ -0,0 +1,568 @@
+// packages/material-library/src/server.ts
+import { defineOperation, PluginError } from "vivix-studio/sdk/server";
+import { z as z2 } from "vivix-studio/sdk/shared";
+import { createHash } from "crypto";
+import { createReadStream } from "fs";
+
+// packages/material-library/src/shared.ts
+import { z } from "vivix-studio/sdk/shared";
+var Config = z.discriminatedUnion("role", [
+  z.object({
+    role: z.literal("service"),
+    dataInstance: z.string().min(1).default("data"),
+    serviceInstance: z.string().min(1).default("library")
+  }).strict(),
+  z.object({
+    role: z.literal("client"),
+    serviceInstance: z.string().min(1).default("user:library")
+  }).strict()
+]);
+var materialFields = z.object({
+  name: z.string().trim().min(1).max(200),
+  kind: z.enum(["text", "image", "video", "audio", "file"]),
+  tags: z.array(z.string().trim().min(1).max(64)).max(50).transform((x) => [...new Set(x)]).default([]),
+  category: z.enum(["character", "scene", "style", "sound", "reference", "other"]).default("other"),
+  description: z.string().max(4e3).default(""),
+  origin: z.enum(["import", "collected"]),
+  sourceRef: z.object({ storeId: z.uuid(), objectId: z.uuid(), versionId: z.uuid() }).strict().nullable().default(null),
+  sourceLabel: z.object({
+    projectName: z.string(),
+    objectName: z.string(),
+    versionNumber: z.number().int().positive()
+  }).strict().nullable().default(null),
+  lifecycle: z.enum(["ready", "archived"]).default("ready"),
+  recommendedVersionId: z.uuid(),
+  licenseNote: z.string().max(4e3).default("")
+}).strict();
+var materialData = materialFields.refine(
+  (v) => v.origin !== "collected" || v.sourceRef !== null,
+  "Collected materials require a fixed source."
+);
+
+// packages/material-library/src/server.ts
+var dependencies = (config) => config.role === "service" ? [config.dataInstance] : [];
+var ownerPackage = "@vivix/material-library";
+var packageVersion = "0.1.22-ecommerce.20261110.1";
+var id = z2.uuid();
+var revision = z2.number().int().positive();
+var ref = z2.object({ storeId: id, objectId: id, versionId: id }).strict();
+var usageSchema = z2.object({
+  materialRef: ref,
+  projectId: z2.string().min(1).max(128),
+  targetAssetId: id,
+  targetVersionId: id,
+  name: z2.string().max(200).default(""),
+  active: z2.boolean().default(true)
+}).strict();
+function fail(code, message) {
+  throw new PluginError(code, message, "Review the material and the current project, then retry.");
+}
+var materialDefinition = {
+  typeId: "library.material",
+  schemaVersion: 1,
+  scopeKinds: ["user"],
+  validate: (value) => materialData.parse(value),
+  validateUpdate: (before, after) => {
+    if (before.kind !== after.kind || before.origin !== after.origin || ["storeId", "objectId", "versionId"].some(
+      (key) => before.sourceRef?.[key] !== after.sourceRef?.[key]
+    ))
+      fail("IMMUTABLE_FIELD", "Material identity and source are immutable.");
+  }
+};
+var usageDefinition = {
+  typeId: "library.usage",
+  schemaVersion: 1,
+  scopeKinds: ["user"],
+  validate: (value) => usageSchema.parse(value),
+  validateUpdate: (before, after) => {
+    if (before.projectId !== after.projectId || before.targetAssetId !== after.targetAssetId || before.targetVersionId !== after.targetVersionId || ["storeId", "objectId", "versionId"].some(
+      (key) => before.materialRef[key] !== after.materialRef[key]
+    ))
+      fail("IMMUTABLE_FIELD", "Usage identities refer to fixed source and target versions.");
+  }
+};
+var operationDescriptions = {
+  "documents.list": "List persisted extension documents in the bound scope. Does not create content.",
+  "documents.create": "Create a persisted extension document with the original write request key.",
+  "documents.update": "Save document content only at its observed revision; preserve the draft on conflict.",
+  "documents.delete": "Delete the specified extension document at its observed revision.",
+  "files.resolveLocation": "Resolve an exact immutable version and optional file ID to a readable local location and preview URL. Does not render or export.",
+  "files.openLocation": "Open the containing directory of an exact readable immutable version. Does not modify its bytes.",
+  "metadata.patch": "Update only the named object metadata using its observed revision and a stable write request key.",
+  "metadata.keys": "List metadata keys available in this binding for building actual queries and views.",
+  "library.list": "List library materials with filters and pagination; materials are distinct from project asset candidates.",
+  "library.get": "Read one material and its immutable saved versions before choosing a fixed reference.",
+  "library.import": "Create a library material from validated staged file IDs and retain its provenance.",
+  "library.importVersion": "Append an immutable material version from validated staged files at the observed revision.",
+  "library.update": "Update material name, tags, or settings at the observed revision while preserving saved bytes.",
+  "library.archive": "Archive the material without rewriting existing project copies or immutable references.",
+  "library.restore": "Restore an archived material without generating new content.",
+  "library.usage": "List actual project uses of the specified material/version. Continue paging until nextOffset is null.",
+  "library.cleanupImpact": "Read references and uses that protect a material before permanent purge.",
+  "library.purge": "Permanently purge eligible material content after impact checks and explicit confirmation."
+};
+function activate(ctx) {
+  if (ctx.config.role === "client") {
+    if (ctx.scope?.kind !== "project")
+      fail("SCOPE_MISMATCH", "Library clients belong to projects.");
+    if (!ctx.config.serviceInstance.startsWith("user:"))
+      fail("INVALID_CONFIG", "Library clients require an explicit user service instance.");
+    return;
+  }
+  if (ctx.scope?.kind !== "user") fail("SCOPE_MISMATCH", "Library services belong to user scope.");
+  if (ctx.config.dataInstance.startsWith("user:"))
+    fail("INVALID_CONFIG", "The user library requires its local data instance.");
+  const scope = { kind: "user", id: ctx.scope.id };
+  const workspace = ctx.plugins.get(ctx.config.dataInstance);
+  const binding = (actorId) => workspace.bind({ scope, ownerPackage, packageVersion, actorId, access: ["data.workspace"] });
+  const data = binding("local");
+  data.register(materialDefinition);
+  data.register(usageDefinition);
+  const localCall = (call, operation) => {
+    const originalRequestKey = call.originalRequestKey ?? call.requestKey;
+    if (!call.requestKey || call.requestKey.length > 128 || !originalRequestKey || originalRequestKey.length > 128)
+      fail("INVALID_REQUEST_KEY", "Request keys must contain 1\u2013128 characters.");
+    const requestKey = "library-" + createHash("sha256").update(
+      JSON.stringify([
+        call.scope?.kind ?? scope.kind,
+        call.scope?.id ?? scope.id,
+        call.actor.id,
+        operation,
+        call.requestKey,
+        originalRequestKey,
+        call.sourceOperation ?? operation
+      ])
+    ).digest("hex");
+    return {
+      ...call,
+      scope,
+      requestKey,
+      originalRequestKey,
+      sourceOperation: call.sourceOperation ?? operation
+    };
+  };
+  const material = (api, objectId, includeDeleted = false) => {
+    const object = api.get(objectId, includeDeleted);
+    if (object.typeId !== "library.material") fail("TYPE_MISMATCH", "Expected a material.");
+    return object;
+  };
+  const assertProject = (projectId, call) => {
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(projectId) || call.scope?.kind !== "project" || call.scope.id !== projectId)
+      fail("SCOPE_MISMATCH", "Projects must actively report their own material usage.");
+  };
+  const handle = (name, input, handler, write = false, confirm = false) => ctx.handle(
+    defineOperation({
+      id: name,
+      title: name,
+      description: operationDescriptions[name] || "Operate on the specified scoped record using the declared schema and observed revision.",
+      input,
+      output: z2.any(),
+      effects: [write ? "write" : "read"],
+      confirm: confirm ? "user" : "none"
+    }),
+    handler
+  );
+  async function importFiles(input, call, snapshot2) {
+    const api = binding(call.actor.id);
+    const operationName = input.materialId ? "library.importVersion" : snapshot2 ? "library.collect" : "library.import";
+    const boundCall = localCall(call, operationName);
+    const receipt = {
+      scope: { ...call.scope ?? scope },
+      actorId: call.actor.id,
+      operation: operationName,
+      requestKey: boundCall.originalRequestKey,
+      invocationRequestKey: call.requestKey,
+      storageRequestKey: boundCall.requestKey,
+      sourceOperation: boundCall.sourceOperation
+    };
+    const replay = api.reserve(operationName, input, boundCall);
+    if (replay) return replay.result;
+    const identityCall = { ...call, requestKey: boundCall.requestKey };
+    const operationId = stable(api.storeId, identityCall, operationName, "import"), objectId = input.materialId || stable(operationId, identityCall, operationName, "object"), versionId = stable(operationId, identityCall, operationName, "version");
+    let stagingIds = input.stagingFileIds;
+    if (snapshot2) {
+      stagingIds = [];
+      for (const file of snapshot2.files) {
+        const staged = await api.stage(file.source, file.originalName, call.actor.id);
+        if (staged.sha256 !== file.sha256 || staged.sizeBytes !== file.sizeBytes)
+          fail("FILE_CORRUPT", "Snapshot bytes do not match the fixed source file.");
+        stagingIds.push(staged.stagingFileId);
+      }
+    }
+    const published = await api.publish(
+      stagingIds,
+      objectId,
+      versionId,
+      operationId,
+      call.actor.id,
+      snapshot2?.files.map((file) => file.role)
+    );
+    if (snapshot2 && published.kind !== snapshot2.kind)
+      fail("TYPE_MISMATCH", "Snapshot bytes do not match the stated kind.");
+    const result = api.operation(operationName, input, boundCall, (transaction) => {
+      const object = input.materialId ? transaction.get(objectId) : transaction.create(
+        "library.material",
+        materialData.parse({
+          name: input.name || snapshot2?.sourceLabel.objectName,
+          kind: published.kind,
+          origin: snapshot2 ? "collected" : "import",
+          sourceRef: snapshot2?.ref || null,
+          sourceLabel: snapshot2?.sourceLabel || null,
+          recommendedVersionId: versionId
+        }),
+        snapshot2?.metadata || {},
+        objectId
+      );
+      if (object.typeId !== "library.material" || object.data.kind !== published.kind)
+        fail("TYPE_MISMATCH", "Content kind does not match the material.");
+      const version = transaction.commitVersion(
+        objectId,
+        input.expectedRevision || object.revision,
+        {
+          versionId,
+          parentVersionId: input.parentVersionId,
+          sourceRef: snapshot2?.ref,
+          origin: snapshot2 ? "copied" : "upload",
+          payload: {
+            ...snapshot2?.payload || {},
+            ...published.details,
+            kind: published.kind,
+            primaryFileId: published.files[0].fileId,
+            attachments: published.files.slice(1).map((file) => ({ fileId: file.fileId, role: file.role })),
+            generation: snapshot2?.payload?.generation || null
+          },
+          metadata: snapshot2?.metadata,
+          files: published.files
+        }
+      );
+      return { material: transaction.get(objectId), version, receipt };
+    });
+    await api.finishFiles(operationId);
+    return result;
+  }
+  const publish = async (input, call) => {
+    const projectId = input.projectId || (call.scope?.kind === "project" ? call.scope.id : "");
+    assertProject(projectId, call);
+    ref.parse(input.ref);
+    const label = materialFields.shape.sourceLabel.parse(input.sourceLabel);
+    if (!label || !input.files.length || input.files.length > 20 || input.files[0].role !== "primary" || input.payload?.primaryFileId !== input.files[0].fileId)
+      fail("INVALID_SNAPSHOT", "A fixed snapshot requires its primary file and source label.");
+    const { files, ...snapshotFields } = input;
+    const intent = {
+      ...snapshotFields,
+      projectId,
+      files: files.map(({ source: _source, ...file }) => file)
+    };
+    return importFiles(intent, call, input);
+  };
+  const snapshot = async (source) => {
+    ref.parse(source);
+    const object = material(data, source.objectId), version = data.version(source), files = data.files(source);
+    const snapshots = [];
+    for (const file of files) {
+      const location = await data.location(source, file.fileId);
+      snapshots.push({
+        ...file,
+        source: (async function* () {
+          yield* createReadStream(location.absolutePath);
+        })()
+      });
+    }
+    return { material: object, version, files: snapshots };
+  };
+  const reportUsage = (input, call) => {
+    const usage = usageSchema.parse(input);
+    assertProject(usage.projectId, call);
+    const api = binding(call.actor.id);
+    material(api, usage.materialRef.objectId, true);
+    api.version(usage.materialRef);
+    const usageId = identity([
+      usage.materialRef,
+      usage.projectId,
+      usage.targetAssetId,
+      usage.targetVersionId
+    ]);
+    return api.operation(
+      "library.usage.upsert",
+      usage,
+      localCall(call, "library.usage.upsert"),
+      (transaction) => {
+        let current;
+        try {
+          current = transaction.get(usageId, true);
+        } catch (error) {
+          if (error.code !== "OBJECT_NOT_FOUND") throw error;
+        }
+        return current ? transaction.update(usageId, current.revision, usage) : transaction.create("library.usage", usage, {}, usageId);
+      }
+    );
+  };
+  const removeUsage = (input, call) => {
+    const removal = z2.object({
+      projectId: z2.string().min(1).max(128),
+      targetAssetId: id,
+      targetVersionId: id.optional(),
+      materialRef: ref.optional()
+    }).strict().parse(input);
+    assertProject(removal.projectId, call);
+    const api = binding(call.actor.id);
+    return api.operation(
+      "library.usage.remove",
+      removal,
+      localCall(call, "library.usage.remove"),
+      (transaction) => {
+        let offset = 0, removed = 0;
+        while (true) {
+          const page = api.list({
+            typeId: "library.usage",
+            targetAssetId: removal.targetAssetId,
+            limit: 200,
+            offset
+          });
+          for (const current of page.items) {
+            const usage = current.data;
+            if (usage.active && usage.projectId === removal.projectId && (!removal.targetVersionId || usage.targetVersionId === removal.targetVersionId) && (!removal.materialRef || ["storeId", "objectId", "versionId"].every(
+              (key) => usage.materialRef[key] === removal.materialRef[key]
+            ))) {
+              transaction.update(current.objectId, current.revision, { ...usage, active: false });
+              removed++;
+            }
+          }
+          if (page.nextOffset === null) return { removed };
+          offset = page.nextOffset;
+        }
+      }
+    );
+  };
+  const service = {
+    data,
+    publish,
+    snapshot,
+    reportUsage,
+    upsertUsage: reportUsage,
+    removeUsage
+  };
+  ctx.provide(service);
+  handle(
+    "library.list",
+    z2.object({
+      search: z2.string().optional(),
+      kind: z2.string().optional(),
+      tag: z2.string().optional(),
+      metadataEquals: z2.record(z2.string(), z2.any()).optional(),
+      metadataContains: z2.record(z2.string(), z2.any()).optional(),
+      sort: z2.enum(["name", "createdAt", "updatedAt"]).optional(),
+      direction: z2.enum(["asc", "desc"]).optional(),
+      limit: z2.number().int().min(1).max(200).optional(),
+      offset: z2.number().int().nonnegative().optional()
+    }).strict(),
+    async (input) => {
+      const result = data.list({ typeId: "library.material", ...input });
+      return {
+        ...result,
+        items: await Promise.all(
+          result.items.map(async (item) => {
+            const versions = data.versions(item.objectId);
+            return {
+              ...item,
+              versions,
+              usageCount: data.usageCount(item.objectId),
+              availability: versions.length ? await data.availability({
+                storeId: data.storeId,
+                objectId: item.objectId,
+                versionId: versions.at(-1).versionId
+              }) : "no_content"
+            };
+          })
+        )
+      };
+    }
+  );
+  handle("library.get", z2.object({ materialId: id }).strict(), (input) => ({
+    material: material(data, input.materialId, true),
+    versions: data.versions(input.materialId),
+    usages: data.usages({ objectId: input.materialId })
+  }));
+  handle(
+    "library.import",
+    z2.object({ name: z2.string().min(1).max(200), stagingFileIds: z2.array(id).min(1).max(20) }).strict(),
+    importFiles,
+    true
+  );
+  handle(
+    "library.importVersion",
+    z2.object({
+      materialId: id,
+      expectedRevision: revision,
+      parentVersionId: id.optional(),
+      stagingFileIds: z2.array(id).min(1).max(20)
+    }).strict(),
+    importFiles,
+    true
+  );
+  handle(
+    "library.update",
+    z2.object({
+      materialId: id,
+      expectedRevision: revision,
+      changes: materialFields.omit({ kind: true, origin: true, sourceRef: true, sourceLabel: true }).extend({
+        tags: materialFields.shape.tags.unwrap(),
+        category: materialFields.shape.category.unwrap(),
+        description: materialFields.shape.description.unwrap(),
+        lifecycle: materialFields.shape.lifecycle.unwrap(),
+        licenseNote: materialFields.shape.licenseNote.unwrap()
+      }).partial().strict()
+    }).strict(),
+    (input, call) => {
+      const api = binding(call.actor.id);
+      return api.operation(
+        "library.update",
+        input,
+        localCall(call, "library.update"),
+        (transaction) => {
+          const object = material(api, input.materialId);
+          if (input.changes.recommendedVersionId)
+            api.version({
+              storeId: api.storeId,
+              objectId: object.objectId,
+              versionId: input.changes.recommendedVersionId
+            });
+          return transaction.update(object.objectId, input.expectedRevision, {
+            ...object.data,
+            ...input.changes
+          });
+        }
+      );
+    },
+    true
+  );
+  for (const action of ["delete", "restore"])
+    handle(
+      "library." + action,
+      z2.object({ materialId: id, expectedRevision: revision }).strict(),
+      (input, call) => {
+        const api = binding(call.actor.id);
+        return api.operation(
+          "library." + action,
+          input,
+          localCall(call, "library." + action),
+          (transaction) => {
+            const object = material(api, input.materialId, true);
+            return transaction.update(
+              object.objectId,
+              input.expectedRevision,
+              object.data,
+              void 0,
+              action === "delete" ? (/* @__PURE__ */ new Date()).toISOString() : null
+            );
+          }
+        );
+      },
+      true
+    );
+  handle(
+    "library.usage",
+    z2.object({
+      materialId: id,
+      versionId: id.optional(),
+      limit: z2.number().int().min(1).max(200).optional(),
+      offset: z2.number().int().nonnegative().optional()
+    }).strict(),
+    (input) => {
+      material(data, input.materialId, true);
+      const limit = input.limit ?? 50, offset = input.offset ?? 0;
+      const items = data.usages({
+        objectId: input.materialId,
+        versionId: input.versionId,
+        limit,
+        offset
+      });
+      const hasMore = data.usages({
+        objectId: input.materialId,
+        versionId: input.versionId,
+        limit: 1,
+        offset: offset + limit
+      }).length > 0;
+      return { items, nextOffset: hasMore ? offset + limit : null };
+    }
+  );
+  const locationInput = z2.union([
+    z2.object({ source: ref, fileId: id.optional() }).strict(),
+    z2.object({ ref, fileId: id.optional() }).strict()
+  ]);
+  handle("files.resolveLocation", locationInput, (input) => {
+    material(data, (input.source || input.ref).objectId, true);
+    return data.location(input.source || input.ref, input.fileId);
+  });
+  handle("files.openLocation", locationInput, async (input) => {
+    material(data, (input.source || input.ref).objectId, true);
+    const location = await data.location(input.source || input.ref, input.fileId);
+    if (process.platform !== "darwin")
+      fail("OPEN_LOCATION_UNAVAILABLE", "Open-location is not verified on this platform.");
+    const { execFile } = await import("child_process"), { promisify } = await import("util");
+    await promisify(execFile)("open", ["-R", location.absolutePath]);
+    return location;
+  });
+  handle(
+    "metadata.patch",
+    z2.object({
+      objectId: id,
+      expectedRevision: revision,
+      set: z2.record(z2.string(), z2.any()),
+      remove: z2.array(z2.string())
+    }).strict(),
+    (input, call) => {
+      const api = binding(call.actor.id);
+      material(api, input.objectId);
+      return api.patchMetadata(
+        input.objectId,
+        input.expectedRevision,
+        input.set,
+        input.remove,
+        localCall(call, "metadata.patch")
+      );
+    },
+    true
+  );
+  handle(
+    "metadata.keys",
+    z2.object({ limit: z2.number().int().min(1).max(200).optional() }).strict(),
+    (input) => data.metadataKeys("library.material", input.limit)
+  );
+  handle("library.cleanupImpact", z2.object({ materialId: id }).strict(), (input) => {
+    material(data, input.materialId, true);
+    return data.impact(input.materialId);
+  });
+  handle(
+    "library.purge",
+    z2.object({ materialId: id, expectedRevision: revision }).strict(),
+    (input, call) => {
+      const api = binding(call.actor.id);
+      material(api, input.materialId, true);
+      return api.purge(input.materialId, input.expectedRevision, localCall(call, "objects.purge"));
+    },
+    true,
+    true
+  );
+}
+function identity(value) {
+  const hash = createHash("sha256").update(JSON.stringify(value)).digest("hex");
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-a${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+}
+function stable(seed, call, operation, name) {
+  if (!call.requestKey) fail("INVALID_REQUEST_KEY", "A request key is required.");
+  return identity([
+    seed,
+    call.scope?.kind ?? "user",
+    call.scope?.id ?? "user",
+    call.actor.id,
+    operation,
+    call.requestKey,
+    name
+  ]);
+}
+export {
+  Config,
+  activate as default,
+  dependencies
+};

package/dist/shared.d.ts

@@ -0,0 +1,341 @@
+import { CallContext as CallContext$1, z } from 'vivix-studio/sdk/shared';
+
+type Scope = {
+    kind: 'user' | 'project';
+    id: string;
+};
+type CallContext = CallContext$1 & {
+    scope?: Scope;
+    confirmed?: boolean;
+    originalRequestKey?: string;
+    sourceOperation?: string;
+};
+type JSONValue = null | boolean | number | string | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+interface RecordValue {
+    storeId: string;
+    scope: Scope;
+    objectId: string;
+    typeId: string;
+    schemaVersion: number;
+    revision: number;
+    data: any;
+    metadata: Record<string, JSONValue>;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+interface VersionRef {
+    storeId: string;
+    objectId: string;
+    versionId: string;
+}
+interface VersionValue {
+    versionId: string;
+    objectId: string;
+    versionNumber: number;
+    schemaVersion: number;
+    parentVersionId: string | null;
+    sourceRef: VersionRef | null;
+    origin: string;
+    taskId: string | null;
+    payload: any;
+    metadata: any;
+    contentDigest: string;
+    createdAt: string;
+}
+interface FileValue {
+    fileId: string;
+    relativePath: string;
+    originalName: string;
+    mimeType: string;
+    sizeBytes: number;
+    sha256: string;
+    createdAt: string;
+    role: string;
+    ordinal: number;
+}
+type ProbeRunner = (path: string, signal?: AbortSignal, context?: {
+    directory: string;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+interface StageOptions {
+    signal?: AbortSignal;
+    probeRunner?: ProbeRunner;
+    onPrepared?: (stagingFileId: string) => void | Promise<void>;
+}
+interface StagedFile {
+    stagingFileId: string;
+    kind: string;
+    mimeType: string;
+    sizeBytes: number;
+    sha256: string;
+    originalName: string;
+    details: Record<string, any>;
+}
+type SqlScalar = null | string | number;
+interface SqlInput {
+    sql: string;
+    params?: SqlScalar[] | Record<string, SqlScalar>;
+    timeoutMs?: number;
+    maxRows?: number;
+    limit?: number;
+    offset?: number;
+}
+type SqlRow = Record<string, JSONValue>;
+interface MutationInput {
+    table: string;
+    action: 'insert' | 'update' | 'delete';
+    key?: Record<string, SqlScalar>;
+    values?: Record<string, SqlScalar>;
+    expectedRevision?: number;
+}
+interface MutationResult {
+    changes: number;
+    items: SqlRow[];
+}
+interface Query {
+    typeId: string;
+    search?: string;
+    kind?: string;
+    tag?: string;
+    targetAssetId?: string;
+    taskId?: string;
+    outputIndex?: number;
+    metadataEquals?: Record<string, JSONValue>;
+    metadataContains?: Record<string, JSONValue>;
+    sort?: 'name' | 'createdAt' | 'updatedAt';
+    direction?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+    includeDeleted?: boolean;
+}
+interface Transaction {
+    get(id: string, includeDeleted?: boolean): RecordValue;
+    create(typeId: string, data: any, metadata?: any, id?: string): RecordValue;
+    update(id: string, expectedRevision: number, data: any, metadata?: any, deletedAt?: string | null): RecordValue;
+    commitVersion(id: string, expectedRevision: number, value: {
+        parentVersionId?: string | null;
+        sourceRef?: VersionRef | null;
+        origin: string;
+        taskId?: string | null;
+        payload: any;
+        metadata?: any;
+        files?: FileValue[];
+        versionId?: string;
+    }): VersionValue;
+    /** Clear only mutable record-level references owned by this binding; version references remain immutable. */
+    removeRelations(sourceObjectId: string, kind: 'reference'): void;
+    relation(sourceObjectId: string, sourceVersionId: string | null, target: VersionRef, kind: 'source' | 'input' | 'reference'): void;
+}
+interface DataAPI {
+    readonly storeId: string;
+    readonly scope: Scope;
+    get(id: string, includeDeleted?: boolean): RecordValue;
+    list(query: Query): {
+        items: RecordValue[];
+        nextOffset: number | null;
+    };
+    query(input: SqlInput): Promise<SqlRow[]>;
+    mutate(input: MutationInput, call: CallContext): Promise<MutationResult>;
+    versions(id: string): VersionValue[];
+    version(ref: VersionRef): VersionValue;
+    files(ref: VersionRef): FileValue[];
+    receipt(name: string, input: unknown, call: CallContext): {
+        result: any;
+    } | null;
+    reserve(name: string, input: unknown, call: CallContext): {
+        result: any;
+    } | null;
+    operation<T>(name: string, input: unknown, call: CallContext, action: (tx: Transaction) => T): T;
+    patchMetadata(id: string, revision: number, set: Record<string, JSONValue>, remove: string[], call: CallContext): RecordValue;
+    metadataKeys(typeId: string, limit?: number): {
+        key: string;
+        types: string[];
+        observedCount: number;
+    }[];
+    stage(source: AsyncIterable<Uint8Array>, originalName: string, actorId: string, options?: StageOptions): Promise<StagedFile>;
+    stageText(text: string, actorId: string): Promise<StagedFile>;
+    publish(stagingIds: string[], objectId: string, versionId: string, operationId: string, actorId: string, fileRoles?: string[]): Promise<{
+        files: FileValue[];
+        details: any;
+        kind: string;
+    }>;
+    finishFiles(operationId: string): Promise<void>;
+    discardStaging(stagingFileId: string): Promise<void>;
+    discardPublication(operationId: string): Promise<void>;
+    location(ref: VersionRef, fileId?: string): Promise<{
+        source: VersionRef;
+        absolutePath: string;
+        fileId: string;
+        mimeType: string;
+        availability: 'ready';
+        previewUrl: string | null;
+    }>;
+    availability(ref: VersionRef): Promise<'ready' | 'missing' | 'corrupt'>;
+    openFile(ref: VersionRef, fileId: string, signal: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    usages(ref: {
+        objectId: string;
+        versionId?: string;
+        limit?: number;
+        offset?: number;
+    }): any[];
+    usageCount(objectId: string): number;
+    documents(action: 'create' | 'update' | 'delete', input: any, call: CallContext): RecordValue;
+    impact(id: string): any;
+    purge(id: string, revision: number, call: CallContext): any;
+}
+
+declare const Config: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    role: z.ZodLiteral<"service">;
+    dataInstance: z.ZodDefault<z.ZodString>;
+    serviceInstance: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    role: z.ZodLiteral<"client">;
+    serviceInstance: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>], "role">;
+type MaterialConfig = z.infer<typeof Config>;
+interface SnapshotFile extends FileValue {
+    source: AsyncIterable<Uint8Array>;
+}
+interface MaterialPublishInput {
+    projectId?: string;
+    ref: VersionRef;
+    sourceLabel: {
+        projectName: string;
+        objectName: string;
+        versionNumber: number;
+    };
+    name?: string;
+    kind: 'text' | 'image' | 'video' | 'audio' | 'file';
+    payload: any;
+    metadata?: Record<string, any>;
+    files: SnapshotFile[];
+}
+interface MaterialSnapshot {
+    material: RecordValue;
+    version: VersionValue;
+    files: SnapshotFile[];
+}
+interface UsageReport {
+    materialRef: VersionRef;
+    projectId: string;
+    targetAssetId: string;
+    targetVersionId: string;
+    name?: string;
+    active?: boolean;
+}
+interface UsageRemoval {
+    projectId: string;
+    targetAssetId: string;
+    materialRef?: VersionRef;
+    targetVersionId?: string;
+}
+interface LibraryReceipt {
+    scope: Scope;
+    actorId: string;
+    operation: string;
+    requestKey: string;
+    invocationRequestKey: string;
+    storageRequestKey: string;
+    sourceOperation: string;
+}
+interface LibraryService {
+    readonly data: DataAPI;
+    publish(input: MaterialPublishInput, call: CallContext): Promise<{
+        material: RecordValue;
+        version: VersionValue;
+        receipt?: LibraryReceipt;
+    }>;
+    snapshot(ref: VersionRef): Promise<MaterialSnapshot>;
+    reportUsage(input: UsageReport, call: CallContext): RecordValue;
+    upsertUsage(input: UsageReport, call: CallContext): RecordValue;
+    removeUsage(input: UsageRemoval, call: CallContext): {
+        removed: number;
+    };
+}
+declare const materialFields: z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        file: "file";
+        text: "text";
+        image: "image";
+        video: "video";
+        audio: "audio";
+    }>;
+    tags: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    category: z.ZodDefault<z.ZodEnum<{
+        character: "character";
+        scene: "scene";
+        style: "style";
+        sound: "sound";
+        reference: "reference";
+        other: "other";
+    }>>;
+    description: z.ZodDefault<z.ZodString>;
+    origin: z.ZodEnum<{
+        import: "import";
+        collected: "collected";
+    }>;
+    sourceRef: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        storeId: z.ZodUUID;
+        objectId: z.ZodUUID;
+        versionId: z.ZodUUID;
+    }, z.core.$strict>>>;
+    sourceLabel: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        projectName: z.ZodString;
+        objectName: z.ZodString;
+        versionNumber: z.ZodNumber;
+    }, z.core.$strict>>>;
+    lifecycle: z.ZodDefault<z.ZodEnum<{
+        ready: "ready";
+        archived: "archived";
+    }>>;
+    recommendedVersionId: z.ZodUUID;
+    licenseNote: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+declare const materialData: z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        file: "file";
+        text: "text";
+        image: "image";
+        video: "video";
+        audio: "audio";
+    }>;
+    tags: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    category: z.ZodDefault<z.ZodEnum<{
+        character: "character";
+        scene: "scene";
+        style: "style";
+        sound: "sound";
+        reference: "reference";
+        other: "other";
+    }>>;
+    description: z.ZodDefault<z.ZodString>;
+    origin: z.ZodEnum<{
+        import: "import";
+        collected: "collected";
+    }>;
+    sourceRef: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        storeId: z.ZodUUID;
+        objectId: z.ZodUUID;
+        versionId: z.ZodUUID;
+    }, z.core.$strict>>>;
+    sourceLabel: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        projectName: z.ZodString;
+        objectName: z.ZodString;
+        versionNumber: z.ZodNumber;
+    }, z.core.$strict>>>;
+    lifecycle: z.ZodDefault<z.ZodEnum<{
+        ready: "ready";
+        archived: "archived";
+    }>>;
+    recommendedVersionId: z.ZodUUID;
+    licenseNote: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+
+export { Config, type LibraryReceipt, type LibraryService, type MaterialConfig, type MaterialPublishInput, type MaterialSnapshot, type SnapshotFile, type UsageRemoval, type UsageReport, materialData, materialFields };

package/dist/shared.js

@@ -0,0 +1,39 @@
+// packages/material-library/src/shared.ts
+import { z } from "vivix-studio/sdk/shared";
+var Config = z.discriminatedUnion("role", [
+  z.object({
+    role: z.literal("service"),
+    dataInstance: z.string().min(1).default("data"),
+    serviceInstance: z.string().min(1).default("library")
+  }).strict(),
+  z.object({
+    role: z.literal("client"),
+    serviceInstance: z.string().min(1).default("user:library")
+  }).strict()
+]);
+var materialFields = z.object({
+  name: z.string().trim().min(1).max(200),
+  kind: z.enum(["text", "image", "video", "audio", "file"]),
+  tags: z.array(z.string().trim().min(1).max(64)).max(50).transform((x) => [...new Set(x)]).default([]),
+  category: z.enum(["character", "scene", "style", "sound", "reference", "other"]).default("other"),
+  description: z.string().max(4e3).default(""),
+  origin: z.enum(["import", "collected"]),
+  sourceRef: z.object({ storeId: z.uuid(), objectId: z.uuid(), versionId: z.uuid() }).strict().nullable().default(null),
+  sourceLabel: z.object({
+    projectName: z.string(),
+    objectName: z.string(),
+    versionNumber: z.number().int().positive()
+  }).strict().nullable().default(null),
+  lifecycle: z.enum(["ready", "archived"]).default("ready"),
+  recommendedVersionId: z.uuid(),
+  licenseNote: z.string().max(4e3).default("")
+}).strict();
+var materialData = materialFields.refine(
+  (v) => v.origin !== "collected" || v.sourceRef !== null,
+  "Collected materials require a fixed source."
+);
+export {
+  Config,
+  materialData,
+  materialFields
+};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@vivix-labs/material-library",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-beta",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "studio-plugin.json",
+    "skills",
+    "presets"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    "./studio-plugin.json": "./studio-plugin.json",
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./shared": {
+      "types": "./dist/shared.d.ts",
+      "import": "./dist/shared.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "peerDependencies": {
+    "vivix-studio": ">=2.1.0-0",
+    "@vivix-labs/creative-data": "1.0.0-beta",
+    "react": "19.3.1"
+  },
+  "devDependencies": {
+    "@vivix-labs/creative-data": "1.0.0-beta"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-product-packages.mjs material-library"
+  }
 }

package/studio-plugin.json

@@ -0,0 +1,6 @@
+{
+  "manifestVersion": "0.2",
+  "id": "material-library",
+  "requirements": { "studioPluginApi": "^0.2.0" },
+  "requestedAccess": []
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.