Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

5.8 KB
Raw Blame
import {
  encodeAssetBundle,
  type AssetLibrary,
  type AssetManifest,
  type AssetRecord,
} from './assets';
import { exportAssetGlb, type AssetGlbExport } from './asset-export';

export interface AssetLink {
  type: 'resource_link';
  name: string;
  uri: string;
  mimeType: string;
  size: number;
  annotations: { audience: ('user' | 'assistant')[]; priority: number };
}

/**
 * Who each artifact is for, and how much it costs to resolve.
 *
 * A `resource_link` deliberately carries no bytes, so the client decides whether to
 * spend context resolving one. `size` and `annotations.audience` are the two fields
 * the spec gives it for that decision, and emitting neither leaves every client
 * guessing from a MIME type -- including the ones that guess "inline everything".
 *
 * `asset.glb` and `preview.png` are download artifacts: the model already receives
 * rendered views as image blocks from `kiln_render` and gets geometry from metrics,
 * so decoding a mesh or re-reading a render buffer buys it nothing. `source.kiln.js`
 * is addressed to both, because re-reading source is a legitimate model move even
 * though `kiln_source` is the cheaper way to do it.
 */
const audiences: Record<string, ('user' | 'assistant')[]> = {
  'asset.glb': ['user'],
  'preview.png': ['user'],
  'manifest.json': ['user'],
  'source.kiln.js': ['user', 'assistant'],
};
const priorities: Record<string, number> = {
  'asset.glb': 0.9,
  'preview.png': 0.8,
  'source.kiln.js': 0.5,
  'manifest.json': 0.3,
};

/**
 * `editable.zip` is deliberately absent. It is a bundle of the files listed beside
 * it, so a client that resolves every advertised link pays for the same bytes twice,
 * and it is the largest entry while being the only derived one. It stays readable at
 * its own URI -- which is what the widget's "Editable bundle" button reads -- and it
 * stays in `downloadUrls` wherever those are configured; it is only unadvertised.
 */
export function assetLinks(collection: string, manifest: AssetManifest): AssetLink[] {
  const manifestBytes = new TextEncoder().encode(JSON.stringify(manifest, null, 2)).byteLength;
  return [...Object.keys(manifest.files), 'manifest.json'].map((name) => ({
    type: 'resource_link' as const,
    name,
    uri: `kiln://assets/${collection}/${manifest.assetId}/${manifest.revisionId}/${name}`,
    mimeType: assetMime(name),
    size: manifest.files[name]?.bytes ?? manifestBytes,
    annotations: {
      audience: audiences[name] ?? ['user'],
      priority: priorities[name] ?? 0.3,
    },
  }));
}
export function assetMime(name: string): string {
  return name.endsWith('.glb')
    ? 'model/gltf-binary'
    : name.endsWith('.png')
      ? 'image/png'
      : name.endsWith('.zip')
        ? 'application/zip'
        : name.endsWith('.json')
          ? 'application/json'
          : 'text/javascript';
}

/** Derived resources are deterministic, read-only, and never replace a saved revision. */
export async function runtimeAssetLinks(
  collection: string,
  record: AssetRecord,
  derived?: Extract<AssetGlbExport, { profile: 'runtime' }>,
): Promise<AssetLink[]> {
  const output = derived ?? (await exportAssetGlb(record, { profile: 'runtime' }));
  if (output.profile !== 'runtime') throw new Error('Expected runtime export');
  return [
    { name: 'runtime.glb', bytes: output.glb },
    { name: output.metadata.name, bytes: output.metadata.bytes },
  ].map(({ name, bytes }) => ({
    type: 'resource_link',
    name,
    uri: `kiln://assets/${collection}/${record.manifest.assetId}/${record.manifest.revisionId}/${name}`,
    mimeType: assetMime(name),
    size: bytes.length,
    annotations: { audience: ['user'], priority: name.endsWith('.glb') ? 0.9 : 0.3 },
  }));
}
/** The built GLB of a program that may never be saved. The URI pins the bytes it was issued for. */
export function programBuildLink(
  programRef: string,
  rendered: { glb: Uint8Array; artifactGlbSha256: string },
): AssetLink {
  return {
    type: 'resource_link',
    name: 'asset.glb',
    uri: `kiln://programs/${encodeURIComponent(programRef)}/${rendered.artifactGlbSha256.replace('sha256:', '')}/asset.glb`,
    mimeType: 'model/gltf-binary',
    size: rendered.glb.byteLength,
    annotations: { audience: ['user'], priority: priorities['asset.glb']! },
  };
}

export async function readAssetResource(
  library: AssetLibrary,
  uri: string,
): Promise<{ bytes: Uint8Array; mimeType: string; name: string }> {
  const match =
    /^kiln:\/\/assets\/([a-z][a-z0-9_-]{0,79})\/([a-z][a-z0-9_-]{0,79})\/([a-z][a-z0-9_-]{0,79})\/(asset\.glb|runtime\.glb|runtime\.kiln-metadata\.json|source\.kiln\.js|preview\.png|manifest\.json|editable\.zip)$/.exec(
      uri,
    );
  if (!match) throw new Error('Unknown asset resource');
  const collection = match[1]!;
  const asset = match[2]!;
  const revision = match[3]!;
  const name = match[4]!;
  const record = await library.read(collection, asset, revision);
  if (name === 'runtime.glb' || name === 'runtime.kiln-metadata.json') {
    const output = await exportAssetGlb(record, { profile: 'runtime' });
    if (output.profile !== 'runtime') throw new Error('Expected runtime export');
    return {
      bytes: name === 'runtime.glb' ? output.glb : output.metadata.bytes,
      mimeType: assetMime(name),
      name,
    };
  }
  const bytes =
    name === 'editable.zip'
      ? await exportLibraryAssetBundle(library, [record])
      : name === 'manifest.json'
        ? new TextEncoder().encode(JSON.stringify(record.manifest, null, 2))
        : record.files[name];
  if (!bytes) throw new Error('Asset file unavailable');
  return { bytes, mimeType: assetMime(name), name };
}

/** One host hook owns exact dependency closure for CLI, MCP and gallery downloads. */
export async function exportLibraryAssetBundle(
  library: AssetLibrary,
  records: AssetRecord[],
): Promise<Uint8Array> {
  return library.exportBundle ? library.exportBundle(records) : encodeAssetBundle(records);
}