Skip to main content

This Runtime Kit Cookbook entry builds the same shape explained in Placeable surfaces: package material becomes named data reads and targets, descriptors declare what each surface may touch, and a dumb shell places the surfaces.

The snippets on this page come from examples/product-cookbook/placeable-surface-product-loop/ and are checked by cookbook-examples.json.

​
When to use this

Use this recipe when the product is bigger than one component.
Good fitNot this recipe
A product shell with multiple surfaces: launch, help, support, settings, billing, or dashboards.A single component reading one data name.
A sidebar/tab/region system that should stay generic.A one-off hardcoded marketing page.
Product areas that need different data names and targets.A pure package-boundary example with no UI shell.
Each new surface keeps adding layout special cases.A reference lookup for one function signature.
The point is not “make a dashboard.” The point is to keep arrangement generic while package-specific UI rules live in package data, targets, descriptors, and surface bodies.

​
What you will build

LayerFilePublic names
Package filelaunch-product/things-to-store-and-run.jsonRecords welcome-copy, checklist; targets launch.next-step, help.search.
Surface descriptorsapp/surfaces.tsSurface ids, labels, regions, component keys, data names, targets.
Dumb shellapp/ProductShell.tsxRenders labels, active surface, and region from descriptors.
Main surfaceapp/LaunchHomeSurface.tsxReads welcome-copy and launch-checklist; calls launch.next-step.
Help surfaceapp/LaunchHelpSurface.tsxCalls help.search with cancellation.

​
What should happen

The shell can show Launch, Help, and Support without hardcoded product branches.
Launch can read package-prepared copy/checklist and call launch.next-step.
Help can call help.search.
Adding another surface means adding descriptor data and a surface body, not editing shell policy.

​
Step 1: package records and targets

The package owns product facts and callable targets.
{
  "package": "launch-product",
  "things": [
    {
      "type": "record",
      "address": "package::launch-product::welcome-copy",
      "payload": {
        "headline": "Your launch stays fast.",
        "body": "Every feature stays behind a package boundary, so the next idea does not have to tangle the last one."
      }
    },
    {
      "type": "record",
      "address": "package::launch-product::checklist",
      "payload": {
        "items": [
          { "id": "account", "label": "Create account", "done": true },
          { "id": "device", "label": "Activate this device", "done": true },
          { "id": "package", "label": "Run a package", "done": false },
          { "id": "target", "label": "Call a target", "done": false }
        ]
      }
    },
    {
      "type": "slot",
      "name": "launch.next-step",
      "methods": [{ "name": "query" }],
      "boundary": {
        "call_shape": "envelope-bytes-in-envelope-bytes-out",
        "methods": [{ "name": "query" }]
      },
      "artifact": { "source_path": "slots/next-step.bin" }
    },
    {
      "type": "slot",
      "name": "help.search",
      "methods": [{ "name": "query" }],
      "boundary": {
        "call_shape": "envelope-bytes-in-envelope-bytes-out",
        "methods": [{ "name": "query" }]
      },
      "artifact": { "source_path": "slots/help-search.bin" }
    }
  ]
}
Runtime Kit admits this package set and prepares the public read/request surface for the app.The package contract is:
Public nameKindUsed by
welcome-copyRecord/data name sourceLaunchHomeSurface
launch-checklistRecord/data name sourceLaunchHomeSurface
launch.next-stepCallable targetLaunchHomeSurface
help.searchCallable targetLaunchHelpSurface

​
Step 2: surface descriptors

A descriptor says where the surface can appear and which Runtime Kit names the surface body may use.
export type SurfaceRegion = 'main' | 'rail' | 'panel';

export type PlaceableSurface = {
  id: string;
  label: string;
  region: SurfaceRegion;
  order: number;
  componentKey: string;
  preparedInputs: string[];
  targets: string[];
};

export const launchSurfaces: PlaceableSurface[] = [
  {
    id: 'launch.home',
    label: 'Launch',
    region: 'main',
    order: 10,
    componentKey: 'surface.launch.home',
    preparedInputs: ['welcome-copy', 'launch-checklist'],
    targets: ['launch.next-step'],
  },
  {
    id: 'launch.help',
    label: 'Help',
    region: 'panel',
    order: 20,
    componentKey: 'surface.launch.help',
    preparedInputs: [],
    targets: ['help.search'],
  },
  {
    id: 'launch.support',
    label: 'Support',
    region: 'panel',
    order: 30,
    componentKey: 'surface.launch.support',
    preparedInputs: [],
    targets: [],
  },
];
Notice what is missing: no dashboard branch, no help branch, no support branch in the shell. The product-specific names are data on the descriptor.Descriptor contract:
FieldWhy it exists
idStable surface identity.
labelText the shell can render without importing package-specific UI code.
regionGeneric placement target such as main, rail, or panel.
orderGeneric sort key.
componentKeyRegistry key for the render body.
preparedInputsPublic read names this surface may use.
targetsPublic action names this surface may call.

​
Step 3: dumb shell

The shell receives surface descriptors and a render registry. It builds navigation from descriptor labels and chooses the active surface by id.
import { useState } from 'react';
import type { PlaceableSurface } from './surfaces';

type SurfaceComponentProps = {
  surface: PlaceableSurface;
};

export type SurfaceRegistry = Record<string, React.ComponentType<SurfaceComponentProps>>;

type ProductShellProps = {
  surfaces: PlaceableSurface[];
  registry: SurfaceRegistry;
};

export function ProductShell({ surfaces, registry }: ProductShellProps) {
  const ordered = [...surfaces].sort((a, b) => a.order - b.order);
  const [activeSurfaceId, setActiveSurfaceId] = useState(ordered[0]?.id ?? '');
  const activeSurface = ordered.find((surface) => surface.id === activeSurfaceId) ?? ordered[0];
  const ActiveSurface = activeSurface ? registry[activeSurface.componentKey] : null;

  return (
    <div className="product-shell">
      <aside aria-label="Product surfaces">
        {ordered.map((surface) => (
          <button
            key={surface.id}
            type="button"
            aria-current={surface.id === activeSurface?.id ? 'page' : undefined}
            onClick={() => setActiveSurfaceId(surface.id)}
          >
            {surface.label}
          </button>
        ))}
      </aside>

      <main data-region={activeSurface?.region ?? 'main'}>
        {activeSurface && ActiveSurface ? <ActiveSurface surface={activeSurface} /> : null}
      </main>
    </div>
  );
}
That shell can place any future surface that follows the descriptor. It does not change when you add analytics, onboarding, billing, settings, or a new customer-facing product area.Shell verification:
CheckPass condition
NavigationRenders from surface.label, not hardcoded product strings.
Active stateTracks surface.id, not component names.
PlacementUses surface.region, not product-specific branches.
Render bodyResolves through surface.componentKey and registry.
Future surfaceAdding a descriptor can add a surface without editing shell policy.

​
Step 4: surface body

The surface body is where product work happens. It reads Runtime Kit data and calls Runtime Kit targets.
import { sendRequestToBitfieldTarget } from '@bitfield/runtime-kit';
import { useBitfieldData } from '@bitfield/runtime-kit/react';
import type { PlaceableSurface } from './surfaces';

type WelcomeCopy = {
  headline: string;
  body: string;
};

type Checklist = {
  items: Array<{ id: string; label: string; done: boolean }>;
};

type NextStepReply = {
  nextStep: string;
  reason: string;
};

export function LaunchHomeSurface({ surface }: { surface: PlaceableSurface }) {
  const welcome = useBitfieldData<WelcomeCopy>('welcome-copy');
  const checklist = useBitfieldData<Checklist>('launch-checklist');

  async function getNextStep(): Promise<NextStepReply> {
    const reply = await sendRequestToBitfieldTarget({
      target: 'launch.next-step',
      payload: {
        surfaceId: surface.id,
        completed: checklist.data?.items.filter((item) => item.done).map((item) => item.id) ?? [],
      },
    });

    return JSON.parse(new TextDecoder().decode(reply.payload)) as NextStepReply;
  }

  if (welcome.loading || checklist.loading) return <section>Loading.</section>;
  if (welcome.error || checklist.error) return <section>Could not load this surface.</section>;
  if (!welcome.data || !checklist.data) return <section>No data yet.</section>;

  return (
    <section>
      <h2>{welcome.data.headline}</h2>
      <p>{welcome.data.body}</p>

      {checklist.data.items.map((item) => (
        <p key={item.id}>{item.done ? 'Done' : 'Next'}: {item.label}</p>
      ))}

      <button type="button" onClick={getNextStep}>
        Show next step
      </button>
    </section>
  );
}
This surface can be moved from main to panel, opened beside another surface, or reused in a different shell. The product work stays with the surface body. The arrangement stays with the shell.Surface body contract:
SurfaceReadsCallsMust render
launch.homewelcome-copy, launch-checklistlaunch.next-steploading, error, empty, success
launch.helpnone in this fixturehelp.searchrequest entry point and request failure in a real UI
launch.supportnone in this fixturenonepublic names placeholder or future body

​
Step 5: second surface, same request primitive

import { useRef } from 'react';
import { sendRequestToBitfieldTarget } from '@bitfield/runtime-kit';

type HelpSearchReply = {
  results: Array<{ title: string; excerpt: string }>;
};

export function LaunchHelpSurface() {
  const current = useRef<AbortController | null>(null);

  async function search(query: string): Promise<HelpSearchReply> {
    current.current?.abort();
    current.current = new AbortController();

    const reply = await sendRequestToBitfieldTarget(
      { target: 'help.search', payload: { query } },
      current.current.signal,
    );

    return JSON.parse(new TextDecoder().decode(reply.payload)) as HelpSearchReply;
  }

  return <button type="button" onClick={() => search('activation')}>Search help</button>;
}
The app has another capability. The shell still did not change.

​
Verify the full loop

Before you call the feature done, write this checklist beside it:
Package set:
  launch-product

Data names:
  welcome-copy
  launch-checklist

Targets:
  launch.next-step
  help.search

Placeable surfaces:
  launch.home -> main -> welcome-copy, launch-checklist -> launch.next-step
  launch.help -> panel -> help.search
  launch.support -> panel -> public names only

Generic shell proof:
  The sidebar renders from surface labels.
  The active region renders from surface.region.
  The render body resolves from surface.componentKey.
  Adding a new surface does not edit shell code.

Public request/reply shapes:
  launch.next-step -> { surfaceId: string; completed: string[] } -> { nextStep: string; reason: string }
  help.search -> { query: string } -> { results: Array<{ title: string; excerpt: string }> }
Check the product loop against this list before it ships. Use the same checklist for teammate code, your own code, or AI-written code.

​
Common failures

SymptomCauseFix
Shell needs a new if (surface.id === ...) branch for every product area.Package-specific UI rules leaked into arrangement.Move those rules into descriptors and registry entries.
Surface calls a target not listed on its descriptor.The surface contract and body drifted.Add the target to the descriptor or remove the call.
Surface reads a data name not listed on its descriptor.The read contract and body drifted.Add the input to the descriptor or change the surface body.
Adding Help requires editing Launch code.Surface bodies are coupled.Keep each surface body behind its own componentKey.
Package setup is imported into the shell.The shell was treated like product code.Reject the output; shell only arranges descriptors.
Reply parsing crashes.Target reply shape changed or was never written.Document request/reply shape and decode only that shape.

​
Safe variations

You can extend this recipe without changing the primitive:
  1. Add launch.analytics in the rail region with its own data name.
  2. Move launch.help from panel to main by changing region.
  3. Add settings.billing with a new component key and target.
  4. Add a second shell that renders the same descriptors differently for mobile.
  5. Add a support surface that reads account/device status once that public names exists.
The shell stays generic in every variation. The product grows by adding descriptors, package material, and surface bodies.

​
Review checklist

The finished product loop should be able to answer:
Package records:
Package stored bytes:
Package targets:
Surface descriptors:
Shell generic proof:
Surface bodies:
Data name use:
Action request use:
Request/reply shapes:
Files changed:
Validation run:
Reject the work if the shell names product concepts in branches, if a surface reads/calls names missing from its descriptor, or if app code imports package implementation files.

​
Next

Read Placeable surfaces when you need the concept behind this recipe.Read Package file for exact package thing fields.Read Runtime Kit API for the public read/request functions.
Last modified on May 10, 2026