تشغيل أي مهارة في Manus بنقرة واحدة

loft-ship

النجوم٦

التفرعات٠

آخر تحديث٤ يوليو ٢٠٢٦ في ٠٧:٥٤

Write, bridge, verify, and publish a loft library so it behaves IDENTICALLY on all four targets — the interpreter, --native, --native-wasm, and --html (browser). Use this skill whenever the user is creating, packaging, cross-compiling, or publishing a loft library or package; mentions loft.toml, the target matrix, a wasm bridge, `loft new` / `loft install`, the registry, the sha256/signature, or making a library "work in the browser" / "work in wasm"; or is debugging native-vs-wasm-vs-interpret divergence in a library. Trigger it even when the user doesn't say "all four platforms" — any loft library that has to ship beyond the interpreter belongs here, because the cross-target parity gate and the wasm-bridge pitfalls are exactly where this work silently goes wrong.

التثبيت

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

تشغيل في Manus

المصدر

loft-lang

loft-lang/loft

فتح مستودع GitHub عرض مستودعات المنشئ

تنزيل

تشغيل في Manus

المهن ذات الصلةSOC

استنادا إلى تصنيف SOC المهني

مطوّرو البرمجياتمهن الحاسوب والرياضيات·SOC 15-1252

مستكشف الملفات

3 ملفات

SKILL.md

readonly

name

loft-ship

description

loft-ship — one source, four targets, identical behavior

A loft library ships to four targets, and the runtime — not the consumer — picks the variant (PACKAGES.md § Target matrix):

	Interpreter	`--native`	`--native-wasm`	`--html` (browser)
Pure loft / `#rust` inline	✓	✓	✓	✓
`#native` external (Rust)	✓ rlib	✓ rlib	✓ wasm rlib	✗ → needs a `wasm.bridge` crate

The master invariant: interpret == native == native-wasm == browser. A library is not shipped until it produces the same observable result on every target it claims. That invariant is the whole job — everything below serves it.

Do this first: the Tier gate (it decides how much work you're in for)

Before scaffolding anything, classify the library — this is the single most leverage-saving step, because the two tiers differ by an order of magnitude:

Tier 1 — pure loft, or #rust inline only. The matrix is ✓ across all four columns: the compiler emits the variant for each target automatically. There is no bridge to build. Shipping = write → loft.toml → cross-mode test → publish. Most libraries are here; keep them here (prefer #rust inline over #native external whenever the Rust is small) precisely so you never enter Tier 2.
Tier 2 — #native external Rust bindings. The browser column has no automatic path: you must hand-build a wasm.bridge crate (host-import module + JS/WASI host shim). This is where the real cost and nearly all the bugs live. Only pay it when the binding genuinely can't be #rust inline (it calls a real host capability: crypto, sockets, the DOM, files).

State which tier you're in out loud — it sets expectations and stops you from over-building a Tier 1 library or under-estimating a Tier 2 one.

The workflow

Scaffold — loft new <name> (or copy a sibling library's loft.toml). See LIBRARY_AUTHORING.md for the full author narrative.
Write the loft surface — the .loft API. For naming/types/format-strings/known-bugs, use the loft-write skill (this skill is about shipping, that one is about writing .loft). Keep the public surface clean per LIBRARY_CHECKLIST.md (Goals A–F apply per library; the stdlib is just the library every program imports).
Declare targets in loft.toml — list the targets the library supports. Tier 2 adds a [wasm.bridge] block. Don't claim a target you haven't passed the parity gate on — a claimed-but-broken target is worse than an honestly-omitted one.
(Tier 2 only) Build the wasm bridge — the host-import module, the host shim, asyncify for any suspending call, and the CBOR ABI across the boundary. This is its own deep procedure with non-obvious traps → read references/wasm-bridge.md before writing a single bridge line.
Run the parity gate (below) — the definition of done.
Publish — build per target, sign, submit to the registry. The signing step has a foot-gun that breaks every install if missed → read references/publish.md.

The parity gate — the definition of "shipped"

Run the library's own tests on every target it claims, and confirm the results match — not just that each exits 0. Bound any --native/wasm run with LOFT_TIMEOUT (the build can hang). The gate, in order of how often each catches a real bug:

--interpret — the baseline (fastest; the reference result).
--native — compiled Rust. Interp/native divergence is the #1 library bug class.
--native-wasm — headless wasm (WASI). Catches VirtFS / no-threading assumptions.
--html (Tier 2) — the browser bridge. Catches the host-shim + asyncify mistakes.

A target passes only when its result equals the interpreter's. "Native works" or "the suite is green" does not close a wasm/browser divergence — that divergence is the bug (it's the same failure mode the stability red-flags chase: two generators reading one IR, drifting). Add a leak check where the library allocates (LOFT_STORES=warn, LOFT_NATIVE_LEAK_CHECK).

Pitfall index — the things that actually cost hours (hard-won, @PLN84)

These are not theoretical; each one bit a real ZT library this cycle. Skim them before you start, not after you're stuck.

The re-sign foot-gun (publish). Editing the registry index.json without re-signing it breaks all loft installs (the locked-baseline check fails: "registry index signature INVALID"). Every registry PR must re-sign. → references/publish.md.
Asyncify for suspending calls (bridge). A bridge function that yields/awaits (a socket read, a frame yield) needs asyncify wiring; yield_frame() only sets a flag, it does not trigger a suspend — a dedicated suspend import (e.g. loft_web.ws_yield) does. → bridge ref.
CBOR ABI drift (bridge). The marshalling across the wasm boundary is where silent corruption hides; validate it with a round-trip value check, not "it didn't crash."
CDN staleness (publish). loft install reads index.json via the raw-GitHub CDN (~1h cache). A just-published version may not resolve as @latest immediately — pin the exact version to verify, and don't conclude "publish failed" from a stale edge.
Claiming the browser column for a #native lib without a bridge. The matrix says ✗ there for a reason — it will compile-fail or silently no-op. Either build the bridge or drop the --html claim.

References (read on demand — don't inline them)

references/wasm-bridge.md — the Tier-2 [wasm.bridge] recipe: host-import module, host shim (host.js browser / WASI headless), asyncify, CBOR ABI, and the @PLN84 traps. Read it the moment a library needs the browser target.
references/publish.md — the registry publish runbook: loft.toml targets, per-target build, Ed25519 sign + re-sign, sha256/size, the CDN gotcha. Read it before any registry submission.
Canonical depth lives in the repo docs — this skill is the procedure + the gate + the traps; point into PACKAGES.md, WASM.md, HTML_EXPORT.md, PKG_REGISTRY.md, REGISTRY_SUBMIT.md for the full reference rather than duplicating them.

المزيد من هذا المستودع

نفس المستودع

draw

loft-lang/loft

Make a considered image or 3D scene from a described intent the iterative-craft way — block in, render, measure, critique against the intent, refine across passes — instead of trying to emit a finished result in one shot. Use this whenever the user wants to DRAW, sketch, illustrate, depict, compose, or paint a 2D picture, OR model / build / lay out a 3D scene, asset, or environment (e.g. a game prop, a room, a character, a landscape), ESPECIALLY when they give a subject, a mood, or a composition to hit ("an old woman at dusk", "a cosy tavern interior", "a low-poly pine tree", "make it feel ominous"). Also use when iterating on or critiquing such an image/scene. Reach for it even if the user doesn't say "iteratively" — the loop is the point, and one-shot guessing is what it replaces. Do NOT use for text-to-image prompts handed to a diffusion model, for charts / plots / diagrams / dashboards (data visualisation), or for UI / web layout.

2026-07-246

loft-write

loft-lang/loft

Reference for writing correct loft code. Apply whenever writing, editing, or reviewing .loft files. Covers types, syntax, known bugs, workarounds, naming rules, and error→fix table.

2026-07-246

loft-plan-workflow

loft-lang/loft

Procedures for plan-shaped work — opening a plan, closing/deferring one, promoting a doc to a plan, choosing the lightest workflow, applying value categories. Apply when the task involves plans, plan directories, a roadmap, or doc-to-plan promotion. The method is tree-agnostic; the concrete paths/templates/tracker that bind it to this repo live in one § at the bottom. Cites source docs for definitions; does not restate.

2026-07-236

engineering-rigor

loft-lang/loft

The shared discipline for any non-trivial change — fixing a bug OR designing/refactoring a load-bearing algorithm. USE THIS when about to fix a non-trivial bug (crash, silent corruption, wrong result), design or refactor a load-bearing algorithm (core representation, runtime, memory, codegen, a public contract or data format), when a change feels fragile or "longer than expected for what it does", or when reaching for an approximation in an exact-invariant domain (geometry, caching, hashing, round-trips) and can't pin the exact construction — ESPECIALLY when a fix already looks obvious (that's the cue, not the exception). It is a SPEED tool, not a brake: a coherent explanation is a hypothesis, not a conclusion, and the fastest route to a fix that sticks is the cheapest probe that could prove your idea wrong (a timing, a grep of a count, one --emit-and-look — seconds). So the moment you can state a cause or a fix, that fluency is the cue to GATHER first, not act — which also lets you fix the SOURCE and delete

2026-07-146

design-protocol

loft-lang/loft

Design Protocol 1 — a design is a testable HYPOTHESIS about an invariant, not a plan you execute. The DESIGN-mode counterpart to the engineering-rigor skill (which routes here for the design half). USE THIS whenever you are about to commit to a load-bearing design — a core representation, runtime, memory model, codegen, a public contract, a data format, or any algorithm that will carry weight: name the ONE invariant, count its re-assertion sites, build the cheapest probe that could FALSIFY each load-bearing claim, then build and validate against the written prediction. And for exact-invariant domains where you cannot even form the invariant (geometry, caching, hashing, store/memory lifetime, round-trips), flip to the constructive instrument — plot a concrete instance of the ANSWER and read the invariant off it. Reach for it when a design feels too clean, when you keep reaching for an approximation, or whenever you catch yourself about to build the first coherent design without probing it.

2026-07-076

loft-codegen

loft-lang/loft

The discipline for ANY loft compiler/codegen work — fixing a store-lifetime or codegen bug, adding/altering bytecode, parser IR, the interpreter, or the native generator, or implementing a language feature that emits ops — OR restructuring any of those without meaning to change what they emit (extracting a selector, folding a special case, deleting a redundant condition). USE THIS the moment you are about to edit src/parser/, src/state/codegen.rs, src/fill.rs, src/generation/, src/compile.rs, or scopes.rs to change OR reshape what code is emitted — ESPECIALLY when a fix looks obvious and you're tempted to "just patch the generator and run the suite." The one load-bearing instrument is the same in both modes — `loft introspect` on BOTH backends BEFORE you touch the compiler — but the gate flips: a BUG FIX proves the WORKING bytecode standalone beside the broken one; a behaviour-PRESERVING REFACTOR proves the emitted IR + native Rust BYTE-IDENTICAL before/after. Skipping it is how codegen work flails and regres

2026-06-256

name

loft-ship

description

loft-ship — one source, four targets, identical behavior

A loft library ships to four targets, and the runtime — not the consumer — picks the variant (PACKAGES.md § Target matrix):

	Interpreter	`--native`	`--native-wasm`	`--html` (browser)
Pure loft / `#rust` inline	✓	✓	✓	✓
`#native` external (Rust)	✓ rlib	✓ rlib	✓ wasm rlib	✗ → needs a `wasm.bridge` crate

Do this first: the Tier gate (it decides how much work you're in for)

Before scaffolding anything, classify the library — this is the single most leverage-saving step, because the two tiers differ by an order of magnitude:

Tier 1 — pure loft, or #rust inline only. The matrix is ✓ across all four columns: the compiler emits the variant for each target automatically. There is no bridge to build. Shipping = write → loft.toml → cross-mode test → publish. Most libraries are here; keep them here (prefer #rust inline over #native external whenever the Rust is small) precisely so you never enter Tier 2.
Tier 2 — #native external Rust bindings. The browser column has no automatic path: you must hand-build a wasm.bridge crate (host-import module + JS/WASI host shim). This is where the real cost and nearly all the bugs live. Only pay it when the binding genuinely can't be #rust inline (it calls a real host capability: crypto, sockets, the DOM, files).

State which tier you're in out loud — it sets expectations and stops you from over-building a Tier 1 library or under-estimating a Tier 2 one.

The workflow

Scaffold — loft new <name> (or copy a sibling library's loft.toml). See LIBRARY_AUTHORING.md for the full author narrative.
Write the loft surface — the .loft API. For naming/types/format-strings/known-bugs, use the loft-write skill (this skill is about shipping, that one is about writing .loft). Keep the public surface clean per LIBRARY_CHECKLIST.md (Goals A–F apply per library; the stdlib is just the library every program imports).
Declare targets in loft.toml — list the targets the library supports. Tier 2 adds a [wasm.bridge] block. Don't claim a target you haven't passed the parity gate on — a claimed-but-broken target is worse than an honestly-omitted one.
(Tier 2 only) Build the wasm bridge — the host-import module, the host shim, asyncify for any suspending call, and the CBOR ABI across the boundary. This is its own deep procedure with non-obvious traps → read references/wasm-bridge.md before writing a single bridge line.
Run the parity gate (below) — the definition of done.
Publish — build per target, sign, submit to the registry. The signing step has a foot-gun that breaks every install if missed → read references/publish.md.

The parity gate — the definition of "shipped"

--interpret — the baseline (fastest; the reference result).
--native — compiled Rust. Interp/native divergence is the #1 library bug class.
--native-wasm — headless wasm (WASI). Catches VirtFS / no-threading assumptions.
--html (Tier 2) — the browser bridge. Catches the host-shim + asyncify mistakes.

Pitfall index — the things that actually cost hours (hard-won, @PLN84)

These are not theoretical; each one bit a real ZT library this cycle. Skim them before you start, not after you're stuck.

The re-sign foot-gun (publish). Editing the registry index.json without re-signing it breaks all loft installs (the locked-baseline check fails: "registry index signature INVALID"). Every registry PR must re-sign. → references/publish.md.
Asyncify for suspending calls (bridge). A bridge function that yields/awaits (a socket read, a frame yield) needs asyncify wiring; yield_frame() only sets a flag, it does not trigger a suspend — a dedicated suspend import (e.g. loft_web.ws_yield) does. → bridge ref.
CBOR ABI drift (bridge). The marshalling across the wasm boundary is where silent corruption hides; validate it with a round-trip value check, not "it didn't crash."
CDN staleness (publish). loft install reads index.json via the raw-GitHub CDN (~1h cache). A just-published version may not resolve as @latest immediately — pin the exact version to verify, and don't conclude "publish failed" from a stale edge.
Claiming the browser column for a #native lib without a bridge. The matrix says ✗ there for a reason — it will compile-fail or silently no-op. Either build the bridge or drop the --html claim.

References (read on demand — don't inline them)

references/wasm-bridge.md — the Tier-2 [wasm.bridge] recipe: host-import module, host shim (host.js browser / WASI headless), asyncify, CBOR ABI, and the @PLN84 traps. Read it the moment a library needs the browser target.
references/publish.md — the registry publish runbook: loft.toml targets, per-target build, Ed25519 sign + re-sign, sha256/size, the CDN gotcha. Read it before any registry submission.
Canonical depth lives in the repo docs — this skill is the procedure + the gate + the traps; point into PACKAGES.md, WASM.md, HTML_EXPORT.md, PKG_REGISTRY.md, REGISTRY_SUBMIT.md for the full reference rather than duplicating them.