@tailorkit/app 0.1.0-beta.17 → 0.1.0-beta.19

package/dist/builder/client-views.d.ts

@@ -0,0 +1,16 @@
+import type { InstanceRegistration } from "./instances";
+export declare function readClientViews(filename: string): Promise<{
+    slot: string;
+    path: string;
+    instances?: true | undefined;
+    disabled?: true | undefined;
+}[]>;
+export declare function readClientManifest(filename: string): Promise<{
+    views: {
+        slot: string;
+        path: string;
+        instances?: true | undefined;
+        disabled?: true | undefined;
+    }[];
+    instanceResolvers: InstanceRegistration[];
+}>;

package/dist/builder/instances.d.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from "vite";
+export interface InstanceModule {
+    filename: string;
+    names: string[];
+}
+export interface InstanceRegistration {
+    slot: string;
+    path: string;
+    resolver: string;
+}
+export declare function extractInstances(filename: string, source: string, root: string, includedNames?: string[]): Promise<{
+    names: string[];
+    server: string;
+    browser: string;
+} | undefined>;
+export declare function instanceExtractionPlugin(root: string, serverConfigured: boolean, modules: Map<string, InstanceModule>): Plugin;
+export declare function instanceServerPlugin(root: string, modules: InstanceModule[]): Plugin;
+export declare function instanceServerImports(modules: InstanceModule[]): string;
+export declare function instanceServerBindings(modules: InstanceModule[], registrations: InstanceRegistration[]): string;

package/dist/builder/server.d.ts

@@ -1,3 +1,6 @@
 import type { LoadedTailorKitConfig } from "../config/loader";
+import type { InstanceModule, InstanceRegistration } from "./instances";
 /** Bundle the private app backend and migrations. */
-export declare function buildServer(loaded: LoadedTailorKitConfig, watch?: boolean, buildOutDir?: string): Promise<import("@voidzero-dev/vite-plus-core/rolldown").RolldownOutput[] | import("@voidzero-dev/vite-plus-core/rolldown").RolldownOutput | import("@voidzero-dev/vite-plus-core/rolldown").RolldownWatcher | undefined>;
+export declare function buildServer(loaded: LoadedTailorKitConfig, watch?: boolean, buildOutDir?: string, instances?: InstanceModule[], registrations?: InstanceRegistration[]): Promise<import("@voidzero-dev/vite-plus-core/rolldown").RolldownOutput[] | import("@voidzero-dev/vite-plus-core/rolldown").RolldownOutput | import("@voidzero-dev/vite-plus-core/rolldown").RolldownWatcher | undefined>;
+/** Check before either build can empty an output directory. */
+export declare function validateServerBuildOutput(loaded: LoadedTailorKitConfig, output: string): void;

package/dist/builder/upload-manifest.d.ts

@@ -8,7 +8,13 @@ export declare const tailorkitUploadManifestSchema: z.ZodObject<{
             light: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
+    views: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        slot: z.ZodString;
+        path: z.ZodString;
+        instances: z.ZodOptional<z.ZodLiteral<true>>;
+        disabled: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strip>>>;
     version: z.ZodLiteral<1>;
 }, z.core.$strip>;
 export type TailorKitUploadManifest = z.output<typeof tailorkitUploadManifestSchema>;
-export declare const createTailorKitUploadManifest: (logos?: TailorKitUploadManifest["assets"]["logos"], server?: boolean) => TailorKitUploadManifest;
+export declare const createTailorKitUploadManifest: (logos?: TailorKitUploadManifest["assets"]["logos"], server?: boolean, views?: TailorKitUploadManifest["views"]) => TailorKitUploadManifest;

package/dist/builder.js

@@ -4,9 +4,9 @@ import {
 import "./chunk-GVB2PAK7.js";
 
 // src/builder/index.ts
-import path6 from "path";
+import path7 from "path";
 import { createRequire as createRequire2 } from "module";
-import { readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { readFile as readFile4, realpath, writeFile as writeFile2 } from "fs/promises";
 
 // ../asset-delivery/dist/logo-validation.mjs
 var maxLogoBytes = 262144;
@@ -96,9 +96,88 @@ var assertSupportedPreactVersion = (version) => {
   return check;
 };
 
+// src/builder/client-views.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+
+// src/builder/upload-manifest.ts
+import { z } from "zod";
+var tailorkitUploadManifestSchema = z.object({
+  assets: z.object({
+    client: z.literal("client/client.js"),
+    server: z.literal("server/server.js").optional(),
+    logos: z.object({
+      dark: z.string().regex(/^client\/logo-dark\.(?:png|svg|webp)$/u).optional(),
+      light: z.string().regex(/^client\/logo-light\.(?:png|svg|webp)$/u).optional()
+    }).optional()
+  }),
+  views: z.array(
+    z.object({
+      slot: z.string().min(1).max(255),
+      path: z.string().startsWith("/").max(1024),
+      instances: z.literal(true).optional(),
+      disabled: z.literal(true).optional()
+    })
+  ).max(1e3).optional(),
+  version: z.literal(1)
+});
+var createTailorKitUploadManifest = (logos, server = false, views) => tailorkitUploadManifestSchema.parse({
+  assets: {
+    client: "client/client.js",
+    ...server ? { server: "server/server.js" } : {},
+    ...logos && Object.keys(logos).length > 0 ? { logos } : {}
+  },
+  views,
+  version: 1
+});
+
+// src/builder/client-views.ts
+var inspectClient = `
+import { readFile } from "node:fs/promises";
+const source = await readFile(process.argv[1], "utf8");
+const { default: client } = await import("data:text/javascript;base64," + Buffer.from(source).toString("base64"));
+if (!client?.slots || typeof client.slots !== "object") throw new Error("Client must default-export defineClient(...)");
+const instanceResolvers = [];
+const views = Object.entries(client.slots).flatMap(([slot, definitions]) =>
+  Object.entries(definitions).flatMap(([path, view]) => {
+    if (view === false) return [{ slot, path, disabled: true }];
+    const resolver = view?.instances?.resolver;
+    if (resolver !== undefined) instanceResolvers.push({ slot, path, resolver });
+    return [{ slot, path, ...(resolver !== undefined ? { instances: true } : {}) }];
+  })
+);
+process.stdout.write("\\nTAILORKIT_VIEWS=" + JSON.stringify({ views, instanceResolvers }));
+process.exit(0);
+`;
+async function readClientManifest(filename) {
+  try {
+    const { stdout } = await promisify(execFile)(
+      process.execPath,
+      ["--input-type=module", "--eval", inspectClient, filename],
+      { timeout: 1e4, maxBuffer: 2 * 1024 * 1024 }
+    );
+    const result = stdout.slice(
+      stdout.lastIndexOf("\nTAILORKIT_VIEWS=") + "\nTAILORKIT_VIEWS=".length
+    );
+    const manifest = JSON.parse(result);
+    const views = tailorkitUploadManifestSchema.shape.views.unwrap().parse(manifest.views);
+    if (!Array.isArray(manifest.instanceResolvers) || manifest.instanceResolvers.some(
+      (ref) => !ref || typeof ref !== "object" || typeof ref.slot !== "string" || typeof ref.path !== "string" || typeof ref.resolver !== "string" || !/^i[0-9a-f]{24}$/u.test(ref.resolver)
+    )) {
+      throw new Error("Invalid instance resolver references");
+    }
+    return { views, instanceResolvers: manifest.instanceResolvers };
+  } catch (error) {
+    throw new Error(
+      "Unable to read app views during the build. Keep browser-only side effects inside components or effects, and default-export defineClient(...).",
+      { cause: error }
+    );
+  }
+}
+
 // src/builder/server.ts
 import { mkdir, mkdtemp as mkdtemp2, writeFile, cp, rm as rm2 } from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 import { build } from "vite";
 
 // src/builder/migrations.ts
@@ -144,11 +223,11 @@ var runtimeManifest = {
 };
 
 // src/builder/schema-check.ts
-import { execFile } from "child_process";
+import { execFile as execFile2 } from "child_process";
 import { access as access2, mkdtemp, readFile as readFile2, readdir as readdir2, rm } from "fs/promises";
 import { tmpdir } from "os";
 import path3 from "path";
-import { promisify } from "util";
+import { promisify as promisify2 } from "util";
 
 // src/builder/drizzle.ts
 import { access } from "fs/promises";
@@ -179,7 +258,7 @@ async function drizzleGenerateArguments(root, output, name) {
 }
 
 // src/builder/schema-check.ts
-var run = promisify(execFile);
+var run = promisify2(execFile2);
 async function snapshot(directory) {
   const entries = await readdir2(directory, { withFileTypes: true }).catch((error) => {
     if (error.code === "ENOENT") return [];
@@ -247,37 +326,428 @@ async function checkAppSchema(root, migrationsDirectory) {
   }
 }
 
+// src/builder/instances.ts
+import { createHash as createHash2 } from "crypto";
+import { readFile as readFile3 } from "fs/promises";
+import path4 from "path";
+import { parseSync, transformWithOxc } from "vite";
+var suffix = "?tailorkit-instances";
+var clientImports = /* @__PURE__ */ new Set([
+  "tailorkit/client",
+  "tailorkit/app/client",
+  "@tailorkit/app/client"
+]);
+var browserGlobals = /* @__PURE__ */ new Set([
+  "window",
+  "document",
+  "navigator",
+  "localStorage",
+  "sessionStorage"
+]);
+function isNode(value) {
+  return !!value && typeof value === "object" && "type" in value;
+}
+function children(node) {
+  return Object.values(node).flatMap(
+    (value) => Array.isArray(value) ? value.filter(isNode) : isNode(value) ? [value] : []
+  );
+}
+function walk(node, visit, ancestors = []) {
+  visit(node, ancestors);
+  for (const child of children(node)) walk(child, visit, [...ancestors, node]);
+}
+function boundNames(node) {
+  if (!node) return [];
+  switch (node.type) {
+    case "Identifier":
+      return [node.name];
+    case "RestElement":
+      return boundNames(node.argument);
+    case "AssignmentPattern":
+      return boundNames(node.left);
+    case "ArrayPattern":
+      return node.elements.flatMap(boundNames);
+    case "ObjectPattern":
+      return node.properties.flatMap(
+        (p) => boundNames(p.type === "Property" ? p.value : p.argument)
+      );
+    default:
+      return [];
+  }
+}
+function declarations(node) {
+  if (node.type === "VariableDeclaration")
+    return node.declarations.flatMap((d) => boundNames(d.id));
+  if (node.type === "FunctionDeclaration" || node.type === "ClassDeclaration")
+    return boundNames(node.id);
+  return [];
+}
+function isFunction(node) {
+  return ["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"].includes(
+    node.type
+  );
+}
+function freeNames(root) {
+  const references = /* @__PURE__ */ new Set();
+  function pattern(node, scope) {
+    if (node.type === "AssignmentPattern") {
+      visit(node.right, scope);
+      pattern(node.left, scope);
+    } else if (node.type === "ObjectPattern") {
+      for (const p of node.properties) {
+        if (p.type === "Property") {
+          if (p.computed) visit(p.key, scope);
+          pattern(p.value, scope);
+        } else pattern(p.argument, scope);
+      }
+    } else if (node.type === "ArrayPattern") {
+      for (const element of node.elements) if (element) pattern(element, scope);
+    } else if (node.type === "RestElement") pattern(node.argument, scope);
+  }
+  function visit(node, parent) {
+    if (node.type === "Identifier") {
+      if (!parent.has(node.name)) references.add(node.name);
+      return;
+    }
+    if (node.type === "ImportDeclaration") return;
+    if (node.type === "ExportSpecifier") {
+      visit(node.local, parent);
+      return;
+    }
+    if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") {
+      let hoisted2 = function(body) {
+        if (isFunction(body)) return;
+        if (body.type === "VariableDeclaration" && body.kind === "var") {
+          for (const name of declarations(body)) scope.add(name);
+        }
+        for (const child of children(body)) hoisted2(child);
+      };
+      var hoisted = hoisted2;
+      const scope = /* @__PURE__ */ new Set([
+        ...parent,
+        ...boundNames(node.id),
+        ...node.params.flatMap(boundNames)
+      ]);
+      if (node.body) hoisted2(node.body);
+      for (const p of node.params) pattern(p, scope);
+      if (node.body) visit(node.body, scope);
+      return;
+    }
+    if (node.type === "BlockStatement" || node.type === "Program") {
+      const scope = /* @__PURE__ */ new Set([...parent, ...node.body.flatMap(declarations)]);
+      for (const statement of node.body) visit(statement, scope);
+      return;
+    }
+    if (node.type === "VariableDeclarator") {
+      pattern(node.id, parent);
+      if (node.init) visit(node.init, parent);
+      return;
+    }
+    if (node.type === "Property" || node.type === "MethodDefinition" || node.type === "PropertyDefinition") {
+      if (node.computed) visit(node.key, parent);
+      if (node.value) visit(node.value, parent);
+      return;
+    }
+    if (node.type === "MemberExpression") {
+      visit(node.object, parent);
+      if (node.computed) visit(node.property, parent);
+      return;
+    }
+    if (node.type === "CatchClause") {
+      const scope = /* @__PURE__ */ new Set([...parent, ...boundNames(node.param)]);
+      if (node.param) pattern(node.param, scope);
+      visit(node.body, scope);
+      return;
+    }
+    if (node.type === "ForStatement" || node.type === "ForInStatement" || node.type === "ForOfStatement") {
+      const declaration = node.type === "ForStatement" ? node.init : node.left;
+      const scope = /* @__PURE__ */ new Set([...parent, ...declaration ? declarations(declaration) : []]);
+      for (const child of children(node)) visit(child, scope);
+      return;
+    }
+    if (node.type === "ClassDeclaration" || node.type === "ClassExpression") {
+      const scope = /* @__PURE__ */ new Set([...parent, ...boundNames(node.id)]);
+      if (node.superClass) visit(node.superClass, scope);
+      visit(node.body, scope);
+      return;
+    }
+    if (node.type === "LabeledStatement") {
+      visit(node.body, parent);
+      return;
+    }
+    if (node.type === "BreakStatement" || node.type === "ContinueStatement") return;
+    for (const child of children(node)) visit(child, parent);
+  }
+  visit(root, /* @__PURE__ */ new Set());
+  return references;
+}
+function property(node, name) {
+  return node.properties.find(
+    (p) => p.type === "Property" && !p.computed && (p.key.type === "Identifier" ? p.key.name === name : p.key.type === "Literal" && p.key.value === name)
+  );
+}
+function parse(filename, source) {
+  const result = parseSync(filename, source);
+  if (result.errors.length)
+    throw new Error(`Unable to parse ${filename}: ${result.errors[0]?.message}`);
+  return result.program;
+}
+function units(program, source) {
+  const imports = [];
+  const statements = [];
+  for (const statement of program.body) {
+    if (statement.type === "ImportDeclaration") {
+      imports.push(statement);
+      continue;
+    }
+    const exported = statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration";
+    const node = statement.type === "ExportNamedDeclaration" && statement.declaration ? statement.declaration : statement;
+    if (node.type === "VariableDeclaration") {
+      for (const d of node.declarations)
+        statements.push({
+          node: d,
+          names: boundNames(d.id),
+          code: `${exported ? "export " : ""}${node.kind} ${source.slice(d.start, d.end)};`,
+          exported
+        });
+    } else
+      statements.push({
+        node,
+        names: declarations(node),
+        code: source.slice(statement.start, statement.end),
+        exported
+      });
+  }
+  return { imports, statements };
+}
+function closure(roots, statements) {
+  const bindings = new Map(statements.flatMap((u) => u.names.map((name) => [name, u])));
+  const names = /* @__PURE__ */ new Set();
+  const selected = /* @__PURE__ */ new Set();
+  function add(name) {
+    if (names.has(name)) return;
+    names.add(name);
+    const unit = bindings.get(name);
+    if (!unit || selected.has(unit)) return;
+    selected.add(unit);
+    for (const ref of freeNames(unit.node)) add(ref);
+  }
+  for (const root of roots) add(root);
+  return { names, selected };
+}
+function renderImports(imports, needed, source, sideEffects) {
+  return imports.flatMap((i) => {
+    if (!i.specifiers.length) return sideEffects ? [source.slice(i.start, i.end)] : [];
+    const parts = i.specifiers.filter((s) => needed(s.local.name));
+    if (!parts.length) return [];
+    const defaultImport = parts.find((s) => s.type === "ImportDefaultSpecifier");
+    const namespace = parts.find((s) => s.type === "ImportNamespaceSpecifier");
+    const named = parts.filter((s) => s.type === "ImportSpecifier");
+    const clauses = [
+      defaultImport?.local.name,
+      namespace ? `* as ${namespace.local.name}` : void 0,
+      named.length ? `{ ${named.map((s) => `${source.slice(s.imported.start, s.imported.end)} as ${s.local.name}`).join(", ")} }` : void 0
+    ].filter(Boolean);
+    return [`import ${clauses.join(", ")} from ${JSON.stringify(i.source.value)};`];
+  }).join("\n");
+}
+async function extractInstances(filename, source, root, includedNames) {
+  const transformed = await transformWithOxc(source, filename, {
+    jsx: { importSource: "preact" },
+    sourcemap: false
+  });
+  source = transformed.code;
+  const program = parse(filename.replace(/\.[^.]+$/u, ".js"), source);
+  const aliases = /* @__PURE__ */ new Set();
+  for (const statement of program.body) {
+    if (statement.type !== "ImportDeclaration" || !clientImports.has(String(statement.source.value)))
+      continue;
+    for (const s of statement.specifiers) {
+      if (s.type === "ImportSpecifier" && s.imported.type === "Identifier" && s.imported.name === "createView")
+        aliases.add(s.local.name);
+    }
+  }
+  let resolvers = [];
+  walk(program, (node, ancestors) => {
+    if (node.type !== "CallExpression" || node.callee.type !== "Identifier" || !aliases.has(node.callee.name))
+      return;
+    const options = node.arguments[1];
+    if (options?.type !== "ObjectExpression") return;
+    const instances = property(options, "instances");
+    if (!instances) return;
+    const fail = (message) => {
+      throw new Error(`${filename}: ${message}`);
+    };
+    if (ancestors.some(isFunction))
+      fail("createView with instances must be declared at module scope.");
+    const owner = ancestors.findLast((n) => n.type === "VariableDeclarator");
+    const viewName = owner?.type === "VariableDeclarator" && owner.id.type === "Identifier" ? owner.id.name : "default";
+    const view = node.arguments[0];
+    if (view?.type !== "Literal" || typeof view.value !== "string")
+      fail("Instance view paths must be string literals.");
+    if (instances.value.type !== "ObjectExpression")
+      fail("instances must be an inline object with dataSchema and resolve.");
+    const config = instances.value;
+    if (config.properties.some((p) => p.type !== "Property" || p.computed || p.kind !== "init"))
+      fail("Instance options cannot contain spreads, getters or computed properties.");
+    const resolve = property(config, "resolve");
+    const schema = property(config, "dataSchema");
+    if (!resolve || !schema || resolve.method || !["ArrowFunctionExpression", "FunctionExpression"].includes(resolve.value.type))
+      fail("instances requires dataSchema and an inline resolve function.");
+    const name = `i${createHash2("sha256").update(
+      `${path4.relative(root, filename).split(path4.sep).join("/")}\0${viewName}\0${view.value}`
+    ).digest("hex").slice(0, 24)}`;
+    if (resolvers.some((r) => r.name === name))
+      fail("Instance resolvers must have distinct module-level variable names.");
+    resolvers.push({
+      name,
+      view: view.value,
+      call: node,
+      instances,
+      resolve,
+      schema
+    });
+  });
+  if (includedNames) {
+    resolvers = resolvers.filter((r) => includedNames.includes(r.name));
+    if (resolvers.length !== includedNames.length)
+      throw new Error(`${filename}: Instance definitions changed; rebuild the app client.`);
+  }
+  if (!resolvers.length) return;
+  const original = units(program, source);
+  const server = closure(
+    resolvers.flatMap((r) => [...freeNames(r.resolve.value), ...freeNames(r.schema.value)]),
+    original.statements
+  );
+  for (const name of server.names) {
+    if (browserGlobals.has(name))
+      throw new Error(`${filename}: Instance resolvers cannot access browser global ${name}.`);
+  }
+  for (const unit of server.selected) {
+    if (resolvers.some((r) => unit.node.start <= r.call.start && unit.node.end >= r.call.end))
+      throw new Error(
+        `${filename}: Instance resolvers cannot capture a view definition. Use the supplied context and queries.`
+      );
+  }
+  const serverSource = [
+    renderImports(original.imports, (name) => server.names.has(name), source, false),
+    ...original.statements.filter((u) => server.selected.has(u)).map((u) => u.code.replace(/^export /u, "")),
+    `export const resolvers = { ${resolvers.map((r) => `${r.name}: { dataSchema: ${source.slice(r.schema.value.start, r.schema.value.end)}, resolve: ${source.slice(r.resolve.value.start, r.resolve.value.end)} }`).join(", ")} };`
+  ].join("\n");
+  let browserSource = source;
+  for (const r of [...resolvers].sort(
+    (a, b) => b.instances.value.start - a.instances.value.start
+  )) {
+    browserSource = browserSource.slice(0, r.instances.value.start) + `{ resolver: ${JSON.stringify(r.name)} }` + browserSource.slice(r.instances.value.end);
+  }
+  const browser = units(parse("browser.js", browserSource), browserSource);
+  const serverBindings = new Set([...server.selected].flatMap((u) => u.names));
+  const browserRoots = browser.statements.filter(
+    (u) => u.exported || !u.names.length || !u.names.some((name) => serverBindings.has(name))
+  );
+  const browserNeeded = closure(
+    browserRoots.flatMap((u) => [...freeNames(u.node), ...u.names]),
+    browser.statements
+  );
+  return {
+    names: resolvers.map((r) => r.name),
+    server: serverSource,
+    browser: [
+      renderImports(
+        browser.imports,
+        (name) => !server.names.has(name) || browserNeeded.names.has(name),
+        browserSource,
+        true
+      ),
+      ...browser.statements.filter((u) => browserRoots.includes(u) || browserNeeded.selected.has(u)).map((u) => u.code)
+    ].join("\n")
+  };
+}
+function instanceExtractionPlugin(root, serverConfigured, modules) {
+  return {
+    name: "tailorkit-instance-extraction",
+    enforce: "pre",
+    async transform(source, filename) {
+      if (filename.includes("node_modules") || !/\.[cm]?[jt]sx?$/u.test(filename) || !source.includes("instances") && !modules.has(filename))
+        return;
+      const result = await extractInstances(filename, source, root);
+      if (!result) {
+        modules.delete(filename);
+        return;
+      }
+      if (!serverConfigured)
+        throw new Error("View instances require server configuration in tailorkit.config.ts.");
+      modules.set(filename, { filename, names: result.names });
+      return { code: result.browser, map: null };
+    }
+  };
+}
+function instanceServerPlugin(root, modules) {
+  return {
+    name: "tailorkit-instance-server-modules",
+    enforce: "pre",
+    resolveId(id) {
+      if (id.endsWith(suffix)) return id;
+    },
+    async load(id) {
+      if (!id.endsWith(suffix)) return;
+      const filename = id.slice(0, -suffix.length);
+      this.addWatchFile(filename);
+      const names = modules.find((module) => module.filename === filename)?.names;
+      const result = await extractInstances(
+        filename,
+        await readFile3(filename, "utf8"),
+        root,
+        names
+      );
+      if (!result)
+        throw new Error(`Instance resolver missing from ${filename}; rebuild the app client.`);
+      return result.server;
+    }
+  };
+}
+function instanceServerImports(modules) {
+  return modules.map(
+    (m, i) => `import { resolvers as instances${i} } from ${JSON.stringify(m.filename + suffix)};`
+  ).join("\n");
+}
+function instanceServerBindings(modules, registrations) {
+  return `[${registrations.map(({ slot, path: viewPath, resolver }) => {
+    const index = modules.findIndex((module) => module.names.includes(resolver));
+    if (index < 0) throw new Error("Instance resolver was not extracted by the app build.");
+    return `{ slot: ${JSON.stringify(slot)}, path: ${JSON.stringify(viewPath)}, ...instances${index}[${JSON.stringify(resolver)}] }`;
+  }).join(", ")}]`;
+}
+
 // src/builder/server.ts
-async function buildServer(loaded, watch = false, buildOutDir) {
+async function buildServer(loaded, watch = false, buildOutDir, instances = [], registrations = []) {
   const config = loaded.config.server;
   if (!config) {
     return;
   }
-  const output = buildOutDir ?? path4.resolve(loaded.root, loaded.config.build?.outDir ?? ".tailorkit");
-  const directory = path4.join(output, "server");
-  const migrationsDirectory = path4.resolve(loaded.root, config.migrations ?? "./migrations");
-  const migrationsOutput = path4.join(output, "migrations");
-  const temporaryRoot = path4.join(output, "tmp");
-  for (const destination of [
-    directory,
-    path4.join(output, "client"),
-    migrationsOutput,
-    temporaryRoot
-  ]) {
-    if (overlaps(migrationsDirectory, destination)) {
-      throw new Error("App build output must not overlap migration source");
-    }
-  }
+  const output = buildOutDir ?? path5.resolve(loaded.root, loaded.config.build?.outDir ?? ".tailorkit");
+  const directory = path5.join(output, "server");
+  const migrationsDirectory = path5.resolve(loaded.root, config.migrations ?? "./migrations");
+  const migrationsOutput = path5.join(output, "migrations");
+  const temporaryRoot = path5.join(output, "tmp");
+  validateServerBuildOutput(loaded, output);
   await rm2(directory, { recursive: true, force: true });
   await mkdir(directory, { recursive: true });
   await mkdir(temporaryRoot, { recursive: true });
-  const temporary = await mkdtemp2(path4.join(temporaryRoot, "server-"));
-  const entry = path4.join(temporary, "entry.mjs");
+  const temporary = await mkdtemp2(path5.join(temporaryRoot, "server-"));
+  const entry = path5.join(temporary, "entry.mjs");
   let watching = false;
+  let ready;
+  const initialBuild = watch ? new Promise((resolve) => {
+    ready = resolve;
+  }) : void 0;
   try {
     await writeFile(
       entry,
-      `export { default } from ${JSON.stringify(path4.resolve(loaded.root, config.entry ?? "src/server.ts"))};
+      `${instances.length ? `import app from ${JSON.stringify(path5.resolve(loaded.root, config.entry ?? "src/server.ts"))};
+import { withInstanceResolvers } from "tailorkit/server";
+${instanceServerImports(instances)}
+export default withInstanceResolvers(app, ${instanceServerBindings(instances, registrations)});` : `export { default } from ${JSON.stringify(path5.resolve(loaded.root, config.entry ?? "src/server.ts"))};`}
 export { default as migrations } from "tailorkit:migrations";
 export const runtimeManifest = ${JSON.stringify(runtimeManifest)};
 `
@@ -286,6 +756,7 @@ export const runtimeManifest = ${JSON.stringify(runtimeManifest)};
       root: loaded.root,
       configFile: false,
       plugins: [
+        instanceServerPlugin(loaded.root, instances),
         {
           name: "tailorkit-app-migrations",
           closeWatcher: () => rm2(temporary, { recursive: true, force: true }),
@@ -303,7 +774,7 @@ export const runtimeManifest = ${JSON.stringify(runtimeManifest)};
               config.migrations === void 0
             );
             await checkAppSchema(loaded.root, migrationsDirectory);
-            this.addWatchFile(path4.join(loaded.root, "src/schema.ts"));
+            this.addWatchFile(path5.join(loaded.root, "src/schema.ts"));
             for (const file of files) {
               this.addWatchFile(file);
             }
@@ -327,55 +798,65 @@ export const runtimeManifest = ${JSON.stringify(runtimeManifest)};
         emptyOutDir: false,
         target: "es2022",
         watch: watch ? {} : null,
+        minify: "oxc",
         rollupOptions: {
           external: [],
-          output: { entryFileNames: "server.js", inlineDynamicImports: true }
+          output: {
+            entryFileNames: "server.js",
+            inlineDynamicImports: true,
+            minify: true,
+            minifyInternalExports: true
+          }
         }
       },
       ssr: { noExternal: true }
     });
     watching = watch;
+    if (watch && "on" in result && initialBuild) {
+      try {
+        await Promise.race([
+          initialBuild,
+          new Promise(
+            (_, reject) => result.on("event", (event) => {
+              if (event.code === "ERROR") reject(event.error);
+              if (event.code === "END") ready?.();
+            })
+          )
+        ]);
+      } catch (error) {
+        await result.close();
+        throw error;
+      }
+    }
     return result;
   } finally {
-    if (!watching) {
-      await rm2(temporary, { recursive: true, force: true });
+    if (!watching) await rm2(temporary, { recursive: true, force: true });
+  }
+}
+function validateServerBuildOutput(loaded, output) {
+  if (!loaded.config.server) return;
+  const migrationsDirectory = path5.resolve(
+    loaded.root,
+    loaded.config.server.migrations ?? "./migrations"
+  );
+  for (const name of ["server", "client", "migrations", "tmp"]) {
+    if (overlaps(migrationsDirectory, path5.join(output, name))) {
+      throw new Error("App build output must not overlap migration source");
     }
   }
 }
 function overlaps(source, destination) {
   const contains = (parent, child) => {
-    const relative = path4.relative(parent, child);
-    return relative === "" || !path4.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path4.sep}`);
+    const relative = path5.relative(parent, child);
+    return relative === "" || !path5.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path5.sep}`);
   };
   return contains(source, destination) || contains(destination, source);
 }
 
-// src/builder/upload-manifest.ts
-import { z } from "zod";
-var tailorkitUploadManifestSchema = z.object({
-  assets: z.object({
-    client: z.literal("client/client.js"),
-    server: z.literal("server/server.js").optional(),
-    logos: z.object({
-      dark: z.string().regex(/^client\/logo-dark\.(?:png|svg|webp)$/u).optional(),
-      light: z.string().regex(/^client\/logo-light\.(?:png|svg|webp)$/u).optional()
-    }).optional()
-  }),
-  version: z.literal(1)
-});
-var createTailorKitUploadManifest = (logos, server = false) => tailorkitUploadManifestSchema.parse({
-  assets: {
-    client: "client/client.js",
-    ...server ? { server: "server/server.js" } : {},
-    ...logos && Object.keys(logos).length > 0 ? { logos } : {}
-  },
-  version: 1
-});
-
 // src/builder/generate-migrations.ts
 import { spawn } from "child_process";
 import { access as access3 } from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 async function generateAppMigrations(options = {}) {
   const loaded = await loadTailorKitConfig(options.configPath, options.cwd);
   if (!loaded.config.server) {
@@ -383,13 +864,13 @@ async function generateAppMigrations(options = {}) {
       "Enable server: {} in tailorkit.config.ts before generating database migrations."
     );
   }
-  await access3(path5.join(loaded.root, "src/schema.ts")).catch((error) => {
+  await access3(path6.join(loaded.root, "src/schema.ts")).catch((error) => {
     throw new Error(
       "Define the app database schema in src/schema.ts before generating migrations.",
       { cause: error }
     );
   });
-  const directory = path5.resolve(loaded.root, loaded.config.server.migrations ?? "./migrations");
+  const directory = path6.resolve(loaded.root, loaded.config.server.migrations ?? "./migrations");
   const args = await drizzleGenerateArguments(loaded.root, directory, options.name);
   await new Promise((resolve, reject) => {
     const child = spawn(process.execPath, args, { cwd: loaded.root, stdio: "inherit" });
@@ -408,35 +889,61 @@ var preactPackageJson = "preact/package.json";
 var preactPackageJsonModuleId = "\0tailorkit-preact-package-json";
 var buildApp = async (options = {}) => {
   const loaded = await loadTailorKitConfig(options.configPath, options.cwd);
-  const entry = path6.resolve(loaded.root, loaded.config.client?.entry ?? "src/client.ts");
-  const serverEntry = path6.resolve(loaded.root, loaded.config.server?.entry ?? "src/server.ts");
+  loaded.root = await realpath(loaded.root);
+  const entry = path7.resolve(loaded.root, loaded.config.client?.entry ?? "src/client.ts");
+  const serverEntry = path7.resolve(loaded.root, loaded.config.server?.entry ?? "src/server.ts");
   const outDir = options.outDir ?? loaded.config.build?.outDir ?? ".tailorkit";
   const preactVersion = getInstalledPreactVersion(loaded.root);
   assertSupportedPreactVersion(preactVersion);
-  const resolvedOutDir = path6.resolve(loaded.root, outDir);
-  const clientOutDir = path6.join(resolvedOutDir, "client");
-  const serverWatcher = await buildServer(loaded, options.watch, resolvedOutDir);
+  const resolvedOutDir = path7.resolve(loaded.root, outDir);
+  validateServerBuildOutput(loaded, resolvedOutDir);
+  const clientOutDir = path7.join(resolvedOutDir, "client");
+  const instanceModules = /* @__PURE__ */ new Map();
+  let serverWatcher;
   const writeBuildExtras = async () => {
+    const { views, instanceResolvers } = await readClientManifest(
+      path7.join(clientOutDir, "client.js")
+    );
+    const resolverNames = new Set(instanceResolvers.map((registration) => registration.resolver));
+    const activeModules = [...instanceModules.values()].map((module) => ({
+      ...module,
+      names: module.names.filter((name) => resolverNames.has(name))
+    })).filter((module) => module.names.length).sort((a, b) => a.filename.localeCompare(b.filename));
+    if (activeModules.reduce((count, module) => count + module.names.length, 0) !== resolverNames.size) {
+      throw new Error(
+        "Client references an instance resolver that was not extracted by the app build."
+      );
+    }
+    if (serverWatcher && "close" in serverWatcher) await serverWatcher.close();
+    serverWatcher = await buildServer(
+      loaded,
+      options.watch,
+      resolvedOutDir,
+      activeModules,
+      instanceResolvers
+    );
     const logoManifest = {};
     for (const variant of ["light", "dark"]) {
       const configuredPath = loaded.config.logos?.[variant];
       if (!configuredPath) {
         continue;
       }
-      const extension = path6.extname(configuredPath).toLowerCase().slice(1);
+      const extension = path7.extname(configuredPath).toLowerCase().slice(1);
       const contentType = { png: "image/png", svg: "image/svg+xml", webp: "image/webp" }[extension];
       if (!contentType) {
         throw new Error(`The ${variant} logo must be an SVG, PNG, or WebP file.`);
       }
-      const content = await readFile3(path6.resolve(loaded.root, configuredPath));
+      const content = await readFile4(path7.resolve(loaded.root, configuredPath));
       validateLogoAsset(content, contentType);
       const filename = `logo-${variant}.${extension}`;
-      await writeFile2(path6.join(clientOutDir, filename), content);
+      await writeFile2(path7.join(clientOutDir, filename), content);
       logoManifest[variant] = `client/${filename}`;
     }
+    await writeFile2(path7.join(clientOutDir, "views.json"), `${JSON.stringify(views)}
+`);
     await writeFile2(
-      path6.join(resolvedOutDir, "tailorkit-upload.json"),
-      `${JSON.stringify(createTailorKitUploadManifest(logoManifest, Boolean(loaded.config.server)), null, 2)}
+      path7.join(resolvedOutDir, "tailorkit-upload.json"),
+      `${JSON.stringify(createTailorKitUploadManifest(logoManifest, Boolean(loaded.config.server), views), null, 2)}
 `,
       "utf-8"
     );
@@ -451,6 +958,15 @@ var buildApp = async (options = {}) => {
     void firstBuild.catch(() => {
     });
   }
+  const completeBuild = async () => {
+    try {
+      await writeBuildExtras();
+      firstBuildDone?.();
+    } catch (error) {
+      firstBuildFailed?.(error instanceof Error ? error : new Error(String(error)));
+      throw error;
+    }
+  };
   const result = await viteBuild({
     build: {
       emptyOutDir: true,
@@ -478,13 +994,14 @@ var buildApp = async (options = {}) => {
     mode: options.mode,
     oxc: { jsx: { importSource: "preact" } },
     plugins: [
+      instanceExtractionPlugin(loaded.root, Boolean(loaded.config.server), instanceModules),
       {
         name: "tailorkit-browser-server-boundary",
         enforce: "pre",
         async resolveId(id, importer) {
           if (/^(?:@tailorkit\/app\/server$|tailorkit\/(?:server|app\/server)$|effect(?:\/|$))/u.test(
             id
-          ) || importer && path6.resolve(path6.dirname(importer), id) === serverEntry) {
+          ) || importer && path7.resolve(path7.dirname(importer), id) === serverEntry) {
             throw new Error(
               "App server implementations cannot be imported into a browser bundle. Import api from #tailorkit and server types with import type."
             );
@@ -503,13 +1020,7 @@ var buildApp = async (options = {}) => {
       {
         name: "tailorkit-preview-build-ready",
         async writeBundle() {
-          try {
-            await writeBuildExtras();
-            firstBuildDone?.();
-          } catch (error) {
-            firstBuildFailed?.(error instanceof Error ? error : new Error(String(error)));
-            throw error;
-          }
+          await completeBuild();
         }
       },
       {
@@ -532,9 +1043,7 @@ var buildApp = async (options = {}) => {
     ],
     root: loaded.root
   }).catch(async (error) => {
-    if (serverWatcher && typeof serverWatcher === "object" && "close" in serverWatcher) {
-      await serverWatcher.close();
-    }
+    if (serverWatcher && "close" in serverWatcher) await serverWatcher.close();
     throw error;
   });
   if (options.watch) {
@@ -551,26 +1060,24 @@ var buildApp = async (options = {}) => {
       if (result && typeof result === "object" && "close" in result) {
         await result.close();
       }
-      if (serverWatcher && typeof serverWatcher === "object" && "close" in serverWatcher) {
-        await serverWatcher.close();
-      }
+      if (serverWatcher && "close" in serverWatcher) await serverWatcher.close();
       throw error;
     }
-  }
-  if (options.watch && result && typeof result === "object" && "close" in result && serverWatcher && typeof serverWatcher === "object" && "close" in serverWatcher) {
-    const clientWatcher = result;
-    return {
-      on: clientWatcher.on.bind(clientWatcher),
-      async close() {
-        await clientWatcher.close();
-        await serverWatcher.close();
-      }
-    };
+    if (result && "close" in result && serverWatcher && "close" in serverWatcher) {
+      const clientWatcher = result;
+      return {
+        on: clientWatcher.on.bind(clientWatcher),
+        async close() {
+          await clientWatcher.close();
+          if (serverWatcher && "close" in serverWatcher) await serverWatcher.close();
+        }
+      };
+    }
   }
   return result;
 };
 function getInstalledPreactVersion(root) {
-  const require2 = createRequire2(path6.join(root, "package.json"));
+  const require2 = createRequire2(path7.join(root, "package.json"));
   try {
     const packageJsonPath = require2.resolve("preact/package.json");
     const packageJson = require2(packageJsonPath);

package/dist/{chunk-3XA36UOQ.js → chunk-43L6XVW6.js}

@@ -8,26 +8,46 @@ import { createContext, h, render } from "preact";
 import { useContext } from "preact/hooks";
 var preactVersion = "10.29.8";
 var createView = (path, options) => {
-  const Context2 = createContext(null);
+  const Context2 = createContext(
+    null
+  );
+  const instances = options.instances;
+  if (instances && !instances.resolver) {
+    throw new Error("View instance resolvers must be compiled with the TailorKit app build.");
+  }
   const View = (props) => {
     if (props.status !== "ready") {
       return null;
     }
+    if (instances && !props.instance) {
+      throw new Error(
+        `View "${path}" requires a selected instance. Pass instanceKey to Slot or instance to Slot.Controlled.`
+      );
+    }
     return h(
       Context2.Provider,
-      { value: props.context },
-      h(options.component, {})
+      { value: { context: props.context, instance: props.instance } },
+      h(options.component, { key: props.instance?.key })
     );
   };
   return {
     component: View,
     path,
+    ...instances?.resolver ? { instances: { resolver: instances.resolver } } : {},
     useContext: () => {
       const context = useContext(Context2);
       if (context === null) {
         throw new Error(`View context is only available while rendering "${path}".`);
       }
-      return context;
+      return context.context;
+    },
+    useInstance: () => {
+      const value = useContext(Context2);
+      if (!value?.instance)
+        throw new Error(
+          `View instance is only available while rendering an instance of "${path}".`
+        );
+      return value.instance;
     }
   };
 };

package/dist/{chunk-46CTW3XJ.js → chunk-7NOEYJOB.js}

@@ -1,3 +1,7 @@
+import {
+  AppError
+} from "./chunk-IJBQ77AH.js";
+
 // src/server/functions.ts
 function query(definition) {
   return Object.freeze({ ...definition, kind: "query" });
@@ -59,6 +63,78 @@ var tk = Object.freeze({
   action: new FunctionBuilder("action", z.undefined(), void 0, {})
 });
 
+// src/server/instances.ts
+import { z as z2 } from "zod";
+var addressSchema = z2.object({
+  slot: z2.string().min(1).max(255),
+  path: z2.string().startsWith("/").max(1024)
+});
+function registeredQueries(functions) {
+  const queries = {};
+  for (const [name, fn] of Object.entries(functions)) {
+    if (isFunction(fn)) {
+      if (fn.kind === "query") queries[name] = fn;
+    } else {
+      const nested = registeredQueries(fn);
+      if (Object.keys(nested).length) queries[name] = nested;
+    }
+  }
+  return queries;
+}
+function withInstanceResolvers(app, resolvers) {
+  if (Object.hasOwn(app.functions, "_tailorkit")) {
+    throw new Error("The _tailorkit function namespace is reserved by TailorKit.");
+  }
+  const queries = registeredQueries(app.functions);
+  const registry = /* @__PURE__ */ new Map();
+  for (const resolver of resolvers) {
+    addressSchema.parse(resolver);
+    let paths = registry.get(resolver.slot);
+    if (!paths) {
+      paths = /* @__PURE__ */ new Map();
+      registry.set(resolver.slot, paths);
+    }
+    if (paths.has(resolver.path)) {
+      throw new Error(
+        `Duplicate instance resolver for slot "${resolver.slot}" and path "${resolver.path}".`
+      );
+    }
+    const result = z2.array(
+      z2.object({
+        key: z2.string().min(1),
+        metadata: z2.record(z2.string(), z2.unknown()),
+        data: resolver.dataSchema
+      })
+    ).refine((items) => new Set(items.map((item) => item.key)).size === items.length, {
+      message: "Instance keys must be unique"
+    });
+    paths.set(resolver.path, { resolver, result });
+  }
+  const instances = {
+    resolve: action({
+      functions: queries,
+      args: addressSchema.extend({ context: z2.record(z2.string(), z2.unknown()) }),
+      async handler({ args, identity, signal, queries: queries2 }) {
+        const entry = registry.get(args.slot)?.get(args.path);
+        if (!entry) throw new AppError("NOT_FOUND", "Instance resolver not found");
+        const value = await entry.resolver.resolve({
+          context: args.context,
+          identity,
+          signal,
+          queries: queries2
+        });
+        const result = entry.result.safeParse(value);
+        if (!result.success) throw new AppError("INTERNAL_SERVER_ERROR", "Invalid function result");
+        return result.data;
+      }
+    })
+  };
+  const internal = defineServer({ instances });
+  return Object.freeze({
+    functions: { ...app.functions, _tailorkit: internal.functions }
+  });
+}
+
 // src/database/schema.ts
 import {
   sqliteTable,
@@ -98,6 +174,7 @@ export {
   action,
   defineServer,
   tk,
+  withInstanceResolvers,
   table,
   text,
   integer,

package/dist/client.js

@@ -10,7 +10,7 @@ import {
   useAction,
   useMutation,
   useQuery
-} from "./chunk-3XA36UOQ.js";
+} from "./chunk-43L6XVW6.js";
 import {
   AppError,
   appError

package/dist/config/config.d.ts

@@ -25,6 +25,7 @@ export interface TailorKitConfig extends z.input<typeof tailorkitConfigSchema> {
     /**
      * ID of the app on the TailorKit host, used for deployment and remote preview.
      * When omitted, the first deployment creates an app and saves its ID here.
+     * The agent command prompts to select or create an app and saves its ID here.
      * Remote preview requires an existing app ID.
      * @default undefined
      */

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   useAction,
   useMutation,
   useQuery
-} from "./chunk-3XA36UOQ.js";
+} from "./chunk-43L6XVW6.js";
 import {
   action,
   and,
@@ -35,8 +35,9 @@ import {
   real,
   table,
   text,
-  tk
-} from "./chunk-46CTW3XJ.js";
+  tk,
+  withInstanceResolvers
+} from "./chunk-7NOEYJOB.js";
 import {
   AppError,
   appError
@@ -78,5 +79,6 @@ export {
   tk,
   useAction,
   useMutation,
-  useQuery
+  useQuery,
+  withInstanceResolvers
 };

package/dist/protocol.js

@@ -2,7 +2,7 @@
 import { oc, type } from "@orpc/contract";
 import { z } from "zod";
 var invocationSchema = z.strictObject({
-  name: z.string().max(512).regex(/^[a-zA-Z][a-zA-Z0-9_]{0,63}(?:\.[a-zA-Z][a-zA-Z0-9_]{0,63})*$/u),
+  name: z.string().max(512).regex(/^(?:[a-zA-Z][a-zA-Z0-9_]{0,63}|_tailorkit)(?:\.[a-zA-Z][a-zA-Z0-9_]{0,63})*$/u),
   args: z.unknown().optional()
 });
 var procedure = oc.errors({

package/dist/server/functions.d.ts

@@ -14,7 +14,7 @@ export type FunctionResult<D> = D extends {
 } ? z.output<R> : D extends {
     handler: (context: never) => infer O;
 } ? Awaited<O> : never;
-type FunctionCalls<F, K extends "query" | "mutation"> = {
+export type FunctionCalls<F, K extends "query" | "mutation"> = {
     readonly [N in keyof F as F[N] extends {
         kind: FunctionKind;
     } ? (F[N] extends {
@@ -87,4 +87,3 @@ export declare function defineServer<const F extends Functions>(functions: F): R
     functions: F;
 }>;
 export type AppDefinition = ReturnType<typeof defineServer>;
-export {};

package/dist/server/instances.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { AppDefinition, Identity } from "./functions";
+interface InstanceResolver {
+    slot: string;
+    path: string;
+    dataSchema: z.ZodType;
+    resolve: (context: {
+        context: Record<string, unknown>;
+        identity: Identity;
+        signal: AbortSignal;
+        queries: unknown;
+    }) => unknown;
+}
+/** Build-generated actions run through the existing authenticated action runtime. */
+export declare function withInstanceResolvers(app: AppDefinition, resolvers: readonly InstanceResolver[]): AppDefinition;
+export {};

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 export { defineServer, query, mutation, action } from "./server/functions";
 export { tk } from "./server/builder";
+export { withInstanceResolvers } from "./server/instances";
 export type { QueryDatabase, MutationDatabase } from "./database/types";
 export type { Identity, FunctionDefinition, AppDefinition, ActionContext, FunctionKind, } from "./server/functions";
 export { table, text, integer, real, boolean, eq, ne, gt, gte, lt, lte, and, or, asc, desc, count, isNull, isNotNull, inArray, } from "./database/schema";

package/dist/server.js

@@ -22,8 +22,9 @@ import {
   real,
   table,
   text,
-  tk
-} from "./chunk-46CTW3XJ.js";
+  tk,
+  withInstanceResolvers
+} from "./chunk-7NOEYJOB.js";
 import {
   AppError
 } from "./chunk-IJBQ77AH.js";
@@ -52,5 +53,6 @@ export {
   real,
   table,
   text,
-  tk
+  tk,
+  withInstanceResolvers
 };

package/dist/views.d.ts

@@ -1,9 +1,29 @@
 import { h } from "preact";
 import type { ComponentChild, ComponentChildren, ComponentType, VNode } from "preact";
+import type { z } from "zod";
+import type { FunctionCalls, Identity } from "./server/functions";
 export interface TailorKitViews {
 }
 export interface TailorKitSlots {
 }
+export interface TailorKitServerFunctions {
+}
+export interface ViewInstance<TData = unknown> {
+    key: string;
+    metadata: Record<string, unknown>;
+    data: TData;
+}
+export interface InstanceResolverContext<TPath extends AppViewPath> {
+    context: ViewContext<TPath>;
+    identity: Identity;
+    signal: AbortSignal;
+    queries: FunctionCalls<TailorKitServerFunctions, "query">;
+}
+export interface ViewInstances<TPath extends AppViewPath, TSchema extends z.ZodType> {
+    dataSchema: TSchema;
+    /** Runs on the app server. Only registered queries are available. */
+    resolve: (context: InstanceResolverContext<TPath>) => ViewInstance<z.input<TSchema>>[] | Promise<ViewInstance<z.input<TSchema>>[]>;
+}
 export type SlotName = keyof TailorKitSlots & string;
 export type ViewPath = Extract<keyof TailorKitViews & string, `/${string}`>;
 export type AppViewPath = ViewPath;
@@ -13,23 +33,32 @@ export type ViewContext<TPath extends AppViewPath> = ViewPropsForPath<TPath> ext
     context: infer TContext;
 } ? TContext : Record<string, never>;
 export type View<TProps extends object = Record<string, never>> = (props: TProps) => ComponentChild;
-export type ViewRuntimeProps<TPath extends AppViewPath> = {
+export type ViewRuntimeProps<TPath extends AppViewPath, TData = unknown> = {
     context: ViewContext<TPath>;
     view: TPath;
     status: "ready";
+    instance?: ViewInstance<TData>;
 } | {
     context?: never;
     view: TPath;
     status: "loading";
+    instance?: never;
 } | {
     context?: never;
     view: TPath;
     status: "error";
+    instance?: never;
 };
-export interface ViewDefinition<TPath extends AppViewPath = AppViewPath> {
+export interface ViewDefinition<TPath extends AppViewPath = AppViewPath, TData = unknown> {
     component: View<ViewRuntimeProps<TPath>>;
     path: TPath;
     useContext: () => ViewContext<TPath>;
+    /** The selected instance, with data inferred from instances.dataSchema. */
+    useInstance: () => ViewInstance<TData>;
+    /** Build-only lookup key connecting this view to its extracted server implementation. */
+    instances?: {
+        resolver: string;
+    };
 }
 type RegisteredViews = {
     [TPath in AppViewPath]: ViewDefinition<TPath>;
@@ -72,9 +101,10 @@ export type TailorKitClientWithMeta<TViews extends SlotDefinitions = SlotDefinit
     $meta: TailorKitClientMeta;
     $runtime: TailorKitClientRuntime;
 };
-export declare const createView: <const TPath extends AppViewPath>(path: TPath, options: {
+export declare const createView: <const TPath extends AppViewPath, TSchema extends z.ZodType>(path: TPath, options: {
     component: View<Record<string, never>>;
-}) => ViewDefinition<TPath>;
+    instances?: ViewInstances<TPath, TSchema>;
+}) => ViewDefinition<TPath, z.output<TSchema>>;
 export declare const defineClient: <const TSlots extends SlotDefinitions>(client: TailorKitClient<TSlots> & {
     slots: { [V in keyof TSlots]: TSlots[V] & RequireViewPaths<TSlots[V]> & RequireMatchingViewKeys<TSlots[V]> & RequireSlotViews<V, TSlots[V]>; };
 } & (Exclude<keyof TSlots, SlotName> extends never ? unknown : {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailorkit/app",
-  "version": "0.1.0-beta.17",
+  "version": "0.1.0-beta.19",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -47,8 +47,8 @@
   "dependencies": {
     "@orpc/client": "2.0.0-beta.40",
     "@orpc/contract": "2.0.0-beta.40",
-    "@tanstack/preact-store": "0.13.3",
-    "@tanstack/store": "0.11.1",
+    "@tanstack/preact-store": "0.13.4",
+    "@tanstack/store": "0.11.2",
     "cosmiconfig": "^10.0.1",
     "drizzle-orm": "1.0.0-rc.4-5d5b77c",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
@@ -57,7 +57,7 @@
   "devDependencies": {
     "@tailorkit/asset-delivery": "0.0.0",
     "@tailorkit/config": "0.0.0",
-    "@types/node": "26.6.3",
+    "@types/node": "26.6.4",
     "happy-dom": "^20.14.5",
     "preact": "^10.29.8",
     "tsup": "^8.5.1",