plyglot

DSL extensibility generator · foundation, map and generation · the two examples are real code

Many languages, layered into one.

A base DSL gives you a grammar and tools. An extension layer adds a vocabulary. Your product then needs its own words: its node types, its fields, its commands. Plyglot is the tool that scaffolds that last layer as one more ply, so your dialect stays a valid document of the layer below and every tool under it keeps working. Then it shows which ply each feature comes from.

Watch a dialect at work Built in three layers Whose feature is it? What the generator emits

Layers
3
Features mapped, with provenance
33
Worked examples, from code on disk
2
Carrier formats
4 · JSON, YAML, TOML, HCL

How people on different layers understand each other, in 27 seconds

The film needs JavaScript, which has not run. Its beats follow.

  1. Three languages stack up: .plyx, the engine scene, generic and powerful with the fewest opinions; .thrd, the whiteboard vocabulary; .tpd, the most opinionated.
  2. Three different people enter at three different layers: an engine builder at .plyx, a whiteboard app maker at .thrd, a debate app maker at .tpd.
  3. A file written at the top is passed down. Each of them can read it, because every layer is a valid document of the layer below.
  4. More people branch their own dialects off each layer, and the picture widens into an ecosystem. Nobody needed an API from anybody else.

Download the film · mp4, 1280 × 720, 27 s, 612 kB · rendered from this same animation by tools/film-export.ts

The idea: three layers, each a valid document of the one below

Extending a language safely is mostly agreeing where your words go. The same three roles show up in a diagram format and in a task-list format.

Three layers on one loom

Eight vertical base threads. Two extension threads are woven across the middle. Two dialect threads are woven across the top. The base threads run unbroken under all of them. base DSL.plyx scene · yap@1 extension layer.thrd vocabulary local dialect.tpd · your members remove this and the cloth below still holds
warp = what you did not write · weft = what you add
  1. The base DSL is the warp: someone else's grammar, validator and tools.
  2. An extension layer weaves a shared vocabulary across it, by contract.
  3. Your dialect is the top weft: your own types and fields, under your namespace.
  4. No layer cuts a thread below it. Lower tools still read the file.
  1. Base DSL

    A grammar, a validator and tools you do not own. It decides what a document is and which parts it will carry without understanding.

    .plyx engine scene · yap@1

  2. Extension layer

    A vocabulary added through the base's own seam: named contracts, registered types, declared in the document so a reader knows what it needs.

    .thrd: thrd:whiteboard, thrd:thread

  3. Local dialect

    One product's words and their implementation details: field shapes, defaults, limits, commands, how the host draws and runs them.

    .tpd pills · a program's task members

Three rules both examples already keep

  1. Everything of yours is namespaced. threadpilled:app/pill, threadpilled:pill/kind.set@1, #@threadpilled:accounts. Two dialects on one base never collide.
  2. A reader that does not know you keeps your data. thrd.it keeps an unknown host namespace through its own edits. Yapture keeps unknown @task members as opaque JSON.
  3. The base's validator still passes. A pill is stored as a card the engine can draw. A roadmap item is a task Yapture can lint. The dialect's own checks run after, not instead.

Scenes: script, extension and state, moving together

Three short films. Each shows a script on the left, what a host makes of it, and the state it leaves behind, one beat at a time. Watch where a layer's line lands, what it changes, and what the layer below still understands.

The films need JavaScript, which has not run. Their beats, in words:

  1. A card becomes a pill. An engine scene gains thrd.it's cards and a thread; ThreadPilled registers its pill type, changes a kind with one command and labels the thread with a relation; thrd.it reopens the file and keeps what it does not know.
  2. A list that runs. A Yapture list gains a program's members; the dialect's check catches a ticked box that Yapture accepts; the host works out what can start and changes state through the dialect. Typed task checks and runner stubs are generated.
  3. Whose feature is it? The tool snapshots each layer's registries and finds that shapes are a parent feature two layers overload.

Use Play, Back and Next, or the arrow keys. The films stop when they leave the screen and do not start by themselves when your system asks for reduced motion.

Worked example A: .plyx → .thrd → .tpd

PlyLoom's engine draws a scene. thrd.it adds a whiteboard vocabulary to it. ThreadPilled adds pills, relations and host data. One document, growing a layer at a time:

The layered document needs JavaScript, which has not run. The three layers are shown as code below.

Assembled for this page from the shapes in thrdit/boards/*.thrd, thrdit/packages/core and threadpilled-app/src/pills. It is the JSON form thrd.it saves; it is not a file copied from disk. A .tpd file holds exactly this text today: ThreadPilled registers .tpd as an export and import format, and .tpd as its own language is planned.

  1. Base: the engine scene and its container specified

    .plyx is PlyLoom's container: artifacts, each in a registered language, each lowering to one thrd: 1 envelope the engine validates and draws.

    • A closed container: ply, requires, meta, artifacts.
    • definePly registers a language with validate, lower, lift.
    • Third-party languages use their own namespace, e.g. acme:poster@1.

    plyloom/rnd/specs/68-bolt.md, B2 and B3. Draft of 2026-11-10: a prototype runs on the PlyLoom site, nothing in the engine.

    launch.plyx · text form (SPEC-68 B2)
    ply 1
    requires [loom:thrd@1, loom:meme@1]
    meta { title: "Launch" }
    artifacts {
      board { type: "whiteboard"  dsl: "loom:thrd@1"  body { requires { "thrd:scene": 1, "thrd:whiteboard": 1 }  scene { … } } }
      card  { type: "meme"  schema: "loom:meme@1"  body { layers [ … ] } }
      gpu   { type: "view"  of: "board"  render { device: "webgpu"  clear: "#101418" } }
    }
    
    PlyLanguage · the registration a language supplies (SPEC-68 B3)
    interface PlyLanguage {
      id: ContractId;                 // "loom:thrd@1", "loom:meme@1"
      kind: "dsl" | "schema";         // dsl: has its own text form; schema: plain .plyx configuration
      ext?: string;                   // kind "dsl" only: its standalone file extension, ".thrd"
      artifact: string;               // artifact type it produces
      validate(body, path): Problem[];
      lower(body, ctx: { title: string }): JsonValue;   // → a valid thrd envelope; pure, deterministic
      lift(doc: JsonValue): Body;                        // lift(lower(b)) = b for every valid b
    }
    definePly(lang): PlyLanguage   // throws on a duplicate id (no silent replacement)
    
  2. Extension layer: thrd.it's vocabulary and its host seams built

    .thrd adds cards, shapes and threads as contracts in requires. For the layer above, the SDK opens five seams. These are what a dialect is made of.

    • Host identity and host commands: your namespace, your registered appliers, one commit each.
    • Host data: one slot per node under meta.host[namespace].
    • registerNodeType: your kind of node, drawn over a carrier the engine knows.
    • registerShape and registerTool: your outlines and toolbar tools.

    thrdit/packages/core/README.md and packages/interaction/README.md, @thrdit/core 0.17.0.

    the five seams · from the @thrdit/core and @thrdit/interaction READMEs
    // 1. Host commands: start from appRegistry(identity), register, and pass it to the Board.
    const registry = appRegistry(identity);                       // identity.commandNamespace: "myapp:app"
    registry.register("myapp:pill/categorise@1", (doc, args) => { /* pure: change doc, return it */ return doc; });
    
    // 2. Host data on a node (0.7.0): stored under meta.host[<namespace>][<node id>]
    board.setHostData(id, { kind: "claim", source: { title: "Reading study" } });   // one commit
    board.hostData(id);                          // { kind: "claim", … } or undefined
    hostDataIn(document, "threadpilled:app");    // every node's data in a namespace, without a Board
    
    // 3. Host node types (0.8.0)
    registerNodeType({
      type: "threadpilled:app/pill", label: "Pill", size: [220, 96],       // carrier: "card" by default, or a shape
      render: (c) => `<text x="10" y="16">${escapeMarkup(c.data?.kind ?? "note")}</text>`,   // SVG, in the node's own box
      inspect: [{ id: "kind", label: "Kind", kind: "select", options, get: (c) => c.data?.kind ?? "claim", set: (c, v) => ({ ...c.data, kind: v }) }],
    });
    
    // 4. Host shapes (0.15.0)
    registerShape({
      id: "myapp:kit/parallelogram", label: "Parallelogram", icon: "M7 5h14l-4 14H3z", size: [180, 90],
      path: (w, h) => `M ${w * 0.2} 0 L ${w} 0 L ${w * 0.8} ${h} L 0 ${h} Z`,   // the outline for a box w by h, closed
    });
    
    // 5. Tools (@thrdit/interaction)
    mountWhiteboard(host, { tools: [...TOOLS, stamp] });      // or registerTool(stamp) before mounting
    
  3. Local dialect: ThreadPilled's pills, relations and host data built .tpd as a language: planned

    ThreadPilled uses those seams and nothing else. The implementation details are its own: four pill kinds, a tolerant reader, limits on every field, three relations, five versioned commands.

    • A pill is the type threadpilled:app/pill on a card carrier, with its fields in host data.
    • Reading never fails: missing or malformed takes a default, an unknown kind is kept.
    • A relation is a thread's label: supports, disputes, cites.
    • .tpd is a registered export and import format whose text is the map's .thrd document. Registering it as a language that extends .thrd, with its own grammar and validation, is open work (TP-04.7, ENG-03.7).

    threadpilled-app/src/canvas/identity.ts, src/canvas/tpd.ts, src/pills/pill.ts, src/pills/commands.ts (excerpts); docs/spec/TP-04, ENG-03.

    src/canvas/identity.ts
    import { appRegistry, hostIdentity, type CommandRegistry, type HostIdentity } from "@thrdit/core";
    import { registerPillCommands } from "../pills/commands.ts";
    
    export const THREADPILLED: HostIdentity = hostIdentity({
      app: "threadpilled",
      systemActor: "app:threadpilled",
      historyKeyPrefix: "threadpilled:history",
      commandNamespace: "threadpilled:app",
    });
    
    /** The command registry a ThreadPilled board runs: the SDK's vocabulary under both namespaces, and ThreadPilled's own commands (TP-04.3). */
    export function threadpilledRegistry(): CommandRegistry {
      const registry = appRegistry(THREADPILLED);
      registerPillCommands(registry);
      return registry;
    }
    
    src/pills/pill.ts · the type, its data and its reader (excerpt)
    export const PILL_TYPE = "threadpilled:app/pill";
    export const PILL_SIZE: readonly [number, number] = [240, 112];
    
    /** Where evidence or a source comes from. Every field is optional. */
    export interface PillSource { url?: string; title?: string; author?: string; date?: string; quote?: string; capturedAt?: string }
    export interface Pill {
      kind: string;
      source?: PillSource;
      tags: string[];
      archived: boolean;
      /** The author's own, 0 to 1. */
      confidence?: number;
    }
    
    /** A pill read from a node's host data. Anything missing or malformed takes its default; an unknown kind is kept. */
    export function readPill(data: JsonValue | undefined): Pill {
      const d = isObj(data) ? data : {};
      const kind = clean(d.kind, 40) || DEFAULT_KIND;
      const source: PillSource = {};
      if (isObj(d.source)) for (const key of SOURCE_FIELDS) { const v = clean(d.source[key], key === "quote" ? 600 : 300); if (v) source[key] = v; }
      const confidence = typeof d.confidence === "number" && d.confidence >= 0 && d.confidence <= 1 ? d.confidence : undefined;
      return {
        kind,
        ...(Object.keys(source).length ? { source } : {}),
        tags: Array.isArray(d.tags) ? normalizeTags(d.tags) : [],
        archived: d.archived === true,
        ...(confidence !== undefined ? { confidence } : {}),
      };
    }
    
    src/pills/commands.ts · commands and relations (excerpt)
    export const PILL_COMMANDS = {
      kind: "threadpilled:pill/kind.set@1",
      source: "threadpilled:pill/source.set@1",
      tags: "threadpilled:pill/tags.set@1",
      archive: "threadpilled:pill/archive.set@1",
      relation: "threadpilled:thread/relation.set@1",
    } as const;
    
    /** The relations a thread may carry (D-16). Which kinds each may join arrives with TP-04.2. */
    export const RELATIONS = ["supports", "disputes", "cites"] as const;
    
    registry.register(PILL_COMMANDS.kind, (doc, args) => changePill(doc, PILL_COMMANDS.kind, args, (_now, a) => {
      if (typeof a.kind !== "string" || !/^[a-z][a-z0-9-]{0,39}$/.test(a.kind)) throw new Error(`${PILL_COMMANDS.kind}: kind must be a lower-case name`);
      return { kind: a.kind };
    }));
    registry.register(PILL_COMMANDS.relation, (doc, args) => {
      const cmd = PILL_COMMANDS.relation;
      if (!isObj(doc) || !isObj(args) || typeof args.thread !== "string") throw new Error(`${cmd}: args must name a thread`);
      if (!isRelation(args.relation)) throw new Error(`${cmd}: relation must be one of ${RELATIONS.join(", ")}`);
      const nodes = isObj(doc.scene) && isObj(doc.scene.nodes) ? doc.scene.nodes : {};
      const thread = own(nodes, args.thread) ? nodes[args.thread] : undefined;
      if (!isObj(thread) || thread.type !== "thrd:thread/thread") throw new Error(`${cmd}: ${args.thread} is not a thread`);
      thread.label = { ...(isObj(thread.label) ? thread.label : {}), text: args.relation };
      return doc;
    });
    

Worked example B: your own language over Yapture's .yap

Yapture's list format is small on purpose. It has one seam, and a real program already uses it: ThreadPilled's roadmap is a dialect of yap@1. Plyglot generates the typed-task declarations and runner stubs in the third step.

The layered document needs JavaScript, which has not run. The layers are shown as code below.

An example list in the acme namespace, written for this page. Steps one and two follow ThreadPilled's real lists; step three shows Plyglot’s generated typed-task runner stub.

  1. Base: the yap@1 grammar built

    A version line, one @list, then tasks and actions. Every record is one physical line. The JSON on a record must have a non-empty id; its other members are opaque to Yapture.

    • That opacity is the seam: your members ride in the @task JSON.
    • Badges such as #@track:area and #!p0 are lexical. The text keeps their spelling.
    • requiredExtensions must be absent or empty, so a yap@1 file cannot declare that it needs a dialect. The dialect is the host's knowledge.

    threadpilled-app/roadmap/vendor/yap/grammar.ebnf and LINT-CONTRACT.md (the pinned @yapture/yap-portable). Its source is Yapture's libs repository (~/Code/github/yapture/libs), which also holds Yapture Script, @yapture/script-dsl, where #^name means a goal rather than ThreadPilled's phase.

    grammar.ebnf · yap@1 (excerpt)
    document = version, EOL, { trivia, EOL }, list, { EOL, (trivia | task | action) }, [ EOL ];
    version = "@yap 1";
    list = "@list ", jsonObject;
    task = "- [", (" " | "x"), "] ", text, EOL,
           "  @task ", jsonObject, { EOL, "  | ", text };
    action = "@action ", jsonObject;
    (* jsonObject: strict JSON with unique object keys, nonempty string id;
       requiredExtensions absent or empty array. Other members are opaque JSON. *)
    
  2. Local dialect: ThreadPilled's roadmap members, their checks and their runner built

    The program defines status, spec, phase, repo, gaps, dependsOn, decision and evidence. Its scripts load lists through Yapture's parse and lint first, then apply the dialect's own rules.

    • Validation: statuses and phases from a closed set, the checkbox agreeing with status, dependencies that exist, no cycles.
    • How the host runs it: next.ts computes what can start, set.ts changes one item, build.ts writes the page.
    • Yapture's own CLI still lints and formats the same files.

    threadpilled-app/roadmap/lists/threadpilled.yap, roadmap/scripts/lib.ts, check.ts (excerpts); docs/spec/PRG-01-tracking.md.

    roadmap/lists/threadpilled.yap · two real items
    @yap 1
    @list {"id":"threadpilled","label":"ThreadPilled","track":"threadpilled"}
    - [ ] Profile per issuer and subject; ThreadPilled account deletion; no credential columns #@threadpilled:accounts #!p1 #^p1
      @task {"id":"TP-01.3","spec":"TP-01","status":"todo","phase":"P1","repo":"threadpilled-api","gaps":["a1"],"dependsOn":["TP-01.2"]}
    - [ ] App: sign in through /auth/sign-in, account menu and signed-in state #@threadpilled:accounts #!p0 #^p1
      @task {"id":"TP-01.5","spec":"TP-01","status":"todo","phase":"P1","repo":"threadpilled-app","gaps":["a1"],"dependsOn":["TP-01.2","TP-01.4"]}
    
    roadmap/scripts/lib.ts · base first, then the dialect's members (excerpt)
    import { lint, parse } from "../vendor/yap/sdk.mjs";
    
    export const STATUSES = ["todo", "doing", "blocked", "done", "deferred"] as const;
    export const PHASES = ["P0", "P1", "P2", "P3", "P4", "P5", "Later"] as const;
    
    const parsed = parse(text);
    for (const d of [...parsed.diagnostics, ...lint(text)]) findings.push({ where: file, message: `${d.code ?? "YAP"}: ${d.message ?? JSON.stringify(d)}` });
    if (!parsed.model) continue;
    for (const task of parsed.model.tasks) {
      const [first = "", ...rest] = task.text.split("\n");
      const m = task.metadata;
      const workspace = /#@([A-Za-z0-9_.-]+):([A-Za-z0-9_.-]+)/.exec(first);
      const pri = /(?:^|\s)#!p(\d)/.exec(first);
      items.push({
        id: String(m.id), completed: task.completed, status: String(m.status ?? "") as Status, spec: String(m.spec ?? ""), phase: String(m.phase ?? ""), repo: String(m.repo ?? ""),
        gaps: Array.isArray(m.gaps) ? m.gaps.map(String) : [], dependsOn: Array.isArray(m.dependsOn) ? m.dependsOn.map(String) : [],
        priority: pri ? Number(pri[1]) : 3, area: workspace?.[2] ?? "", track: workspace?.[1] ?? track,
        // …
      });
    }
    
    roadmap/scripts/check.ts and lib.ts · the dialect's validation and its runner (excerpt)
    // 3. Each item is well formed.
    for (const item of items) {
      const at = `${item.file} ${item.id}`;
      if (!STATUSES.includes(item.status)) add(at, `status "${item.status}" is not one of ${STATUSES.join(", ")}`);
      if (item.completed !== (item.status === "done")) add(at, `checkbox is ${item.completed ? "[x]" : "[ ]"} but status is ${item.status}`);
      if (!specIds.has(item.spec)) add(at, `spec ${item.spec || "(none)"} has no file in docs/spec`);
      for (const dep of item.dependsOn) {
        const target = byId.get(dep);
        if (!target) add(at, `depends on ${dep}, which does not exist`);
        else if (item.status === "done" && target.status !== "done") add(at, `is done but depends on ${dep}, which is ${target.status}`);
      }
    }
    
    /** Items that can start now: todo, every dependency done, decision (if any) answered. */
    export function ready(items: Item[]): Item[] {
      const byId = new Map(items.map((i) => [i.id, i]));
      return items
        .filter((i) => !i.isDecision && i.status === "todo")
        .filter((i) => i.dependsOn.every((d) => byId.get(d)?.status === "done"))
        .filter((i) => !i.decision || byId.get(i.decision)?.status === "done")
        .sort(order);
    }
    
    running it · threadpilled-app/roadmap/README.md
    bun roadmap/scripts/next.ts                    # what can start now, and the decisions holding work
    bun roadmap/scripts/set.ts TP-01.1 doing       # change one item; rebuilds and checks
    bun roadmap/scripts/check.ts                   # lint lists, ids, dependencies, gap coverage, vendored hashes
    bun roadmap/vendor/yap/cli.mjs lint roadmap/lists/threadpilled.yap   # Yapture's own tool, same file
    
  3. Typed tasks with a runner generated

    Members are enough for status tracking. A language of your own wants task types: an approval, a deploy gate, a data check. Plyglot generates their checks and runner stubs without changing the grammar.

    • A kind member names a type in your namespace, versioned like a command: acme:task/approval@1.
    • Each type brings declared checks and a write-once run stub for the host to implement.
    • The base grammar is checked first. A task with no kind stays a plain task. An unknown kind is reported and never run.

    examples/yap-tasks/dialect.ts and src/emitters/yap.ts. The example below is generated by the real emitter. Validation uses the pinned Yapture SDK; the host implements each task body.

    acme.tasks.ts · generated stub
    // Written once by plyglot. Task runners belong to the dialect author.
    import { runYapTask, type YapRunner, type YapCheckContext } from "plyglot/yap";
    import { CONFIG } from "./acme.schema.ts";
    export interface Host { requestApproval?(id: string, approvers: readonly string[]): unknown | Promise<unknown> }
    export const TASK_KINDS: Record<string, YapRunner<Host>> = {
      "acme:task/approval@1": async (_task, _host) => {
        // TODO: implement acme:task/approval@1. Only validated known kinds reach this body.
        throw new Error("TODO: implement acme:task/approval@1");
      },
    };
    export function run(source: string, id: string, host: Host, context?: YapCheckContext) { return runYapTask(CONFIG, source, id, TASK_KINDS, host, context); }
    

Feature map: where each feature comes from

Once a language has layers, the first question about any feature is whose it is. Pick a layer to stand on, then a feature: the map says whether it is a parent's, a sibling's, this layer's own or a child's, what it does, and, when a layer overloads it, what differs.

The feature map is generated from pinned source and declarations. P1 reads the PlyLoom engine, thrd.it SDK 0.19.1 and ThreadPilled in separate Bun processes. Owners, relations, field differences and withheld shapes are computed by the shared core. The thrd.it app lane is catalogued but not introspected. The Yapture family adds grammar and lint features, Script’s goal badge and both roadmaps’ declared members and checks. bun src/cli/main.ts map --from threadpilled writes the same map as a self-contained local page.

The feature map needs JavaScript, which has not run.

Try: view from ThreadPilled and pick Shapes (a parent feature it overloads), Pills (its own addition), or shape/triangle (withheld). Every row names the pinned file it was read from.

What the generator produces thrd.it implemented

Both examples were written by hand, and both repeat the same four pieces. Plyglot's job is to emit those pieces from one description of your dialect, and to show the result as a map of whose feature is whose.

Generation works for thrd.it and Yapture dialects. Schema, tolerant readers, preserving writers, registration stubs and a test harness come from one config. The examples below are regenerated from the same emitters. Strict SDK source typechecking still finds an upstream actor-kind mismatch. Required contracts now resolve through the engine’s public catalog, with an explicit resolver for registered hosts. Yapture emits member checks, task runner stubs, fixtures, export profiles and tests against the real SDK.

  1. 1 · Namespace and schemaacme.schema.ts
    Type ids, command ids, field shapes and limits, in one namespace.
  2. 2 · Validatorsacme.validate.ts
    A reader that never throws and a writer that keeps fields it does not know.
  3. 3 · Registration stubsacme.register.ts
    The calls into the base's seams, with the render and run bodies left for you.
  4. 4 · Conformance testacme.conformance.test.ts
    Proof that the base still accepts the document and a stranger keeps your data.
  5. 5 · Feature mapfeature-map.json
    Every feature with its owner, its relation to your layer and what an overload changes. Read from the registries.

The feature map, derived instead of drawn built for the diagram chain

The map above is the fifth thing the tool is meant to produce, and the only one that reads rather than writes. Each base adapter lists what a layer registers, the namespace of every id says which layer owns it, and an id that two layers define differently is an overload. Nobody draws it. The sketch below describes the implemented registry adapter.

Registry interfaces · implementation: src/adapters/thrd/introspect.ts
// Interface sketch. The implemented worker loads one pinned layer per Bun process.
import { exportFormats, importFormats, nodeTypes, shapeCatalog, TOOLS } from "@thrdit/core";

export function snapshot(layer: LayerRef, registry: CommandRegistry, tools = TOOLS): Snapshot {
  return {
    layer: layer.id, parent: layer.parent,
    features: [
      ...nodeTypes().map((t) => feature("node type", t.type, t)),                // "threadpilled:app/pill"
      ...shapeCatalog().map((s) => feature("shape", s.id, s)),                   // the engine's eight, then host shapes
      ...exportFormats().map((f) => feature("format", f.id, f)),                 // "tpd"
      ...importFormats().map((f) => feature("format", f.id, f)),
      ...tools.map((t) => feature("tool", t.id, t)),                             // the list the host mounts
      ...commandIds(registry).map((id) => feature("command", id)),               // implemented: wrap register until upstream ids() exists
    ],
  };
}

// Run once per layer, bottom up. Then, for every feature id:
//   only in the child's snapshot          → added by the child
//   in the parent's, unchanged            → inherited
//   in both, with a different definition  → overloaded: the diff is the two definitions, field by field
//   explicitly excluded by the child    → withheld (ThreadPilled's toolbar and five of the eight shapes)
//   owner = first defining layer         → engine owns thrd:ink/shape; descendants overload it
export function featureMap(snapshots: Snapshot[]): FeatureMap { /* … */ }
terminal · offline CLI
bun src/cli/main.ts map --from threadpilled # writes JSON, data JS and self-contained HTML
bun src/cli/main.ts map --feature thrd:ink/shape   # one feature: owner, relation, and the diff per layer

For yap@1, the adapter reads the pinned grammar and lint contract, then each dialect’s declared members and checks. Features that exist only in a spec (ThreadPilled's comments) would come from the spec's front matter and be marked planned.

The input

plyglot.config.ts · generator input
import { defineDialect } from "plyglot";

export default defineDialect({
  "name": "acme-notes",
  "base": "thrd",
  "namespace": "acme:app",
  "ext": ".acme",
  "nodeTypes": {
    "note": {
      "carrier": "card",
      "size": [
        220,
        96
      ],
      "data": {
        "kind": {
          "enum": [
            "idea",
            "risk",
            "decision"
          ],
          "default": "idea",
          "normalize": "space",
          "max": 40
        },
        "owner": {
          "type": "string",
          "max": 80,
          "optional": true,
          "normalize": "space"
        }
      }
    }
  },
  "commands": {
    "note/kind.set@1": {
      "args": {
        "node": "node",
        "kind": "data.kind"
      }
    }
  }
});
terminal · offline CLI
bunx plyglot init --base thrd --namespace acme:app   # writes plyglot.config.ts
bunx plyglot generate                                # writes code, fixtures, harness and JSON Schema
bunx plyglot check                                   # checks drift and runs the harness

The output

acme.schema.ts · generated output
// GENERATED by plyglot. Do not edit; regenerate from plyglot.config.ts.
export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
export const NAMESPACE = "acme:app";
export const DIALECT_CONFIG = {
  "base": "thrd",
  "commands": {
    "note/kind.set@1": {
      "args": {
        "kind": "data.kind",
        "node": "node"
      }
    }
  },
  "ext": ".acme",
  "name": "acme-notes",
  "namespace": "acme:app",
  "nodeTypes": {
    "note": {
      "carrier": "card",
      "data": {
        "kind": {
          "default": "idea",
          "enum": [
            "idea",
            "risk",
            "decision"
          ],
          "max": 40,
          "normalize": "space"
        },
        "owner": {
          "max": 80,
          "normalize": "space",
          "optional": true,
          "type": "string"
        }
      },
      "size": [
        220,
        96
      ]
    }
  }
} as const;
export const COMMANDS = {
  "note/kind.set@1": "acme:note/kind.set@1"
} as const;
export const NOTE_TYPE = "acme:app/note";
export const NOTE_SIZE: readonly [number, number] = [220,96];
export const NOTE_FIELDS = {
  "kind": {
    "default": "idea",
    "enum": [
      "idea",
      "risk",
      "decision"
    ],
    "max": 40,
    "normalize": "space"
  },
  "owner": {
    "max": 80,
    "normalize": "space",
    "optional": true,
    "type": "string"
  }
};
export const NOTE_KIND_VALUES = ["idea","risk","decision"] as const;
export const DEFAULT_NOTE_KIND = "idea";
export interface Note {
  "kind": string;
  "owner"?: string;
}

With base: "yap", the generator emits a members schema, checks after parse and lint, task kinds with write-once run stubs, an export profile, fixtures and runnable law/conformance tests.

One dialect, editor tools and four formats

The same config supplies language tooling, JSON Schema and format conversion. Everything runs locally with pinned dependencies.

Language tooling JSON-carried thrd.it dialects

The language server provides base-first diagnostics, completion, provenance hover, definitions, formatting and semantic tokens that distinguish base, extension and dialect. YAML, TOML and HCL diagnostics point back into the carrier text. Capabilities can be disabled in tooling.lsp.

plyglot editor emits local Neovim, VS Code, Helix, Zed and Emacs packages. Neovim uses its JSON parser and the shared server. The standalone thrd text grammar and the Zed compiled extension remain verification gaps; their source is supplied, with no download or marketplace step.

terminal · local editor packages
bunx --no-install plyglot editor --target nvim
bunx --no-install plyglot lsp                 # stdio; started by the editor

JSON, YAML, TOML and HCL round-trip laws tested

Converters use one document model and Plyglot-owned printers. Unsupported values fail with their JSON pointers unless the config explicitly declares the loss. TOML cannot carry null. HCL supports data attributes, labelled blocks, objects, tuples and literals; expressions and interpolation are rejected at their source spans.

plyglot generate also emits dialect.schema.json. The real YAML language server is tested against that schema. Codec tests cover 1,000 seeded models per format for both acme-notes and ThreadPilled.

terminal · checked conversion
bunx --no-install plyglot convert map.tpd --to yaml --out map.tpd.yaml
bunx --no-install plyglot convert map.tpd.yaml --to tpd --out roundtrip.tpd

Built, specified, planned

Every claim on this page about another project was checked against that project's files on 15 November 2026. This is where each piece stands.

PieceStandsWhere it was read
.thrd documents: scene, contracts in requiresbuiltthrd.it boards on diskthrdit/boards/*.thrd
thrd.it host seams: identity and commands, host data, node types, shapes, toolsbuilt@thrdit/core 0.17.0thrdit/packages/core/README.md, packages/interaction/README.md
ThreadPilled pills, pill commands, relationsbuiltStored inside .thrdthreadpilled-app/src/pills/*, src/canvas/identity.ts
yap@1 grammar, parse and lintbuiltVendored @yapture/yap-portablethreadpilled-app/roadmap/vendor/yap/
ThreadPilled's roadmap dialect over .yapbuiltLists and Bun scriptsthreadpilled-app/roadmap/lists, roadmap/scripts
.plyx container and definePlyspecifiedSPEC-68, Draft; prototype on the PlyLoom site onlyplyloom/rnd/specs/68-bolt.md
.tpd as an export and import format (its text is the .thrd document)builtRegistered through thrd.it's format registrythreadpilled-app/src/canvas/tpd.ts
.tpd as a registered language with its own grammarplannedTP-04.7 and ENG-03.7 are todo; language extends is not in SPEC-68threadpilled-app/docs/spec/TP-04, ENG-03
ThreadPilled comments, profiles, follows, upvotesplannedSpecified; all eight TP-05 items are todothreadpilled-app/docs/spec/TP-05-social.md
Feature map on this page: relations, overload markers and diffs computed from a layer treebuiltGenerated from pinned registries; shared with the CLIassets/feature-map.data.js; src/viewer
Hero film: a programmatic animation, drawn as a function of timebuiltThe six branch dialects it shows are illustrations, not productssites/plyglot/assets/film.js
Scenes on this page: three films of script, stage and statebuiltScripted by hand from the same sources; the third shows the planned toolsites/plyglot/assets/scenes.js
Feature map derived automatically from the layers' registries (plyglot map)generatedPlyLoom, thrd.it SDK, ThreadPilled; app lane catalogued only; Yapture grammar, Script and two roadmaps mappedsrc/adapters/thrd, src/core, src/cli; assets/feature-map.data.js
Typed tasks (kind) and a runner over YapturegeneratedTyped checks and host-owned runner stubsexamples/yap-tasks; src/yap; src/emitters/yap.ts
Plyglot: defineDialect, the CLI, the thrd and yap adapters, the conformance kitplannedFoundation, both map families and both generators implemented; SDK typing and official editor-schema acceptance gaps recordeddocs/spec/README.md; src/core, src/adapters/thrd, src/cli