lecodes-cli 2.4.0 → 2.4.2

package/src/dev/devServer.ts

@@ -1,4 +1,5 @@
-import { createReadStream, statSync } from "node:fs"
+import { createHash } from "node:crypto"
+import { createReadStream, readFileSync, statSync } from "node:fs"
 import { join } from "node:path"
 import { Readable } from "node:stream"
 import type { Manifest } from "../project/manifest"
@@ -14,6 +15,7 @@ import { toKey } from "../project/paths"
 import { makeStackDemangler } from "../compile/nativeStack"
 import type { WebRunner } from "./webRunner"
 import { createProjectBackend } from "./projectBackend"
+import { buildHalf, halfModule, projectHalves, type ProjectHalf } from "../web/halves"
 
 /*
  * The `lecodes dev` LAN server: serves the project to devices and hot-reloads it on change. It
@@ -35,7 +37,12 @@ import { createProjectBackend } from "./projectBackend"
  *                                the native prelude; the player owns reload (ws / version
  *                                polling) and the log backchannel. A phone is sent here at once
  *   GET /t/<tok>/lite/[file]     the page of Web Lite (lecodes-web-lite's dist), opened as
- *                                lite/?dev=.. — the same bundle.js?t=web, the same reload and logs
+ *                                lite/?dev=.. — the same bundle.js?t=web, the same reload and logs;
+ *                                the project's own web halves (web/halves.ts) under it as a build
+ *                                has them — lite/plugins/<folder>/index.js (built with each
+ *                                compile), its `web.static` folder from the project, and
+ *                                lite/plugins.json naming them for their ids (before the
+ *                                first-party half of the id: its fallback)
  *   POST /t/<tok>/server/api/<id>  the project's backend (its `*.server.ts` files, run on this
  *   WS   /t/<tok>/server/ws        machine — projectBackend.ts): the wire of sdk/src/runtime/rpc.ts,
  *                                the one the runner serves on le.codes
@@ -63,8 +70,12 @@ export type DevServerOptions = {
   /** What is served under /web/ (src/dev/webRunner.ts): the player, and the page around it; absent =
    *  no browser route. */
   web?: WebRunner | null
-  /** The page of Web Lite (lecodes-web-lite's dist), served under /lite/; absent = no such route. */
+  /** The page of Web Lite (lecodes-web-lite's dist), served under /lite/; absent = no such route.
+   *  With it, every compile builds the project's own web halves too (web/halves.ts). */
   lite?: string | null
+  /** Serve over https with this certificate (`lecodes web dev --https`, dev/https.ts); `origin`
+   *  says https then. */
+  tls?: { cert: string, key: string }
   /** Diagnostics (compile errors, device logs); defaults to stderr-style silence-safe noop. */
   log?: (msg: string) => void
   /** The folder of the backend's database (default `.lecodes/db`; the browser tests keep their own). */
@@ -189,9 +200,12 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
       const onWarning = (w: string) => { warnings.push(w) }
       const serverBundle = await backend.compile(entries)
       const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader, onWarning, serverUrl: serverBundle ? serverUrl : undefined })
+      // the page's own halves, before anything is told to reload: one that does not build fails the
+      // compile, the page keeps the last good ones
+      const halvesChanged = lite ? await buildHalves() : false
       // the backend takes the new bundle once the app compiled, and before devices are told to reload
       warnings.push(...await backend.run(serverBundle))
-      const changed = bundleJs === null || stripVolatile(js) !== stripVolatile(bundleJs)
+      const changed = bundleJs === null || stripVolatile(js) !== stripVolatile(bundleJs) || halvesChanged
       if (changed) {
         bundleJs = js
         v++
@@ -203,6 +217,36 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     }
   }
 
+  // ---- the project's own web halves (web/halves.ts), for the page of Web Lite -----------------------
+  // Built with every compile; plugins.json names each by its hash (`index.js?h=…`), so a page that
+  // imported a half sees it changed and loads again (a half is imported once per document).
+  let halves: { half: ProjectHalf, js: string, hash: string }[] = []
+  const buildHalves = async (): Promise<boolean> => {
+    const next: typeof halves = []
+    for (const half of projectHalves(root)) {
+      const js = await buildHalf(half, { dev: true })
+      next.push({ half, js, hash: createHash("sha256").update(js).digest("hex").slice(0, 10) })
+    }
+    const key = (list: typeof halves) => list.map((h) => `${h.half.id}=${h.half.folder}@${h.hash}`).join(";")
+    const changed = key(next) !== key(halves)
+    halves = next
+    return changed
+  }
+  /** The page's plugins.json: Web Lite's first-party halves, the project's BEFORE theirs — a
+   *  project's half of an id is tried first, the first-party one takes the page where it declines
+   *  (`"ar": ["plugins/ar-8thwall/index.js?h=…", "plugins/ar/index-….js"]`, as `web build` writes). */
+  const liteTable = (): Record<string, string | string[]> => {
+    let plugins: Record<string, string> = {}
+    try { plugins = (JSON.parse(readFileSync(join(lite!, "plugins.json"), "utf8")) as { plugins?: Record<string, string> }).plugins ?? {} } catch { /* a page without plugins */ }
+    const table: Record<string, string | string[]> = { ...plugins }
+    for (const { half, hash } of halves) {
+      const own = `${halfModule(half)}?h=${hash}`
+      const firstParty = plugins[half.id]
+      table[half.id] = firstParty !== undefined ? [own, firstParty] : own
+    }
+    return table
+  }
+
   // ---- the project's backend (projectBackend.ts), started with the first compile that has server files
   const backend = createProjectBackend({ root, log, dbDir: options.dbDir, command: "lecodes dev" })
   /** What the app's stubs call. Baked with the advertised origin; a bundle is served with the origin
@@ -259,9 +303,11 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     const transport = transportOf(url)
     return transport === "web" ? js : js + "\n" + renderPrelude({ origin: reqOrigin, base, transport, v })
   }
-  // The backend's url likewise: the app calls it through the origin the bundle was fetched from.
+  // Every url of this server the bundle names likewise — its assets, its shaders, the backend: the
+  // app reaches them through the origin the bundle was fetched from. (`web dev` advertises
+  // localhost; a phone that opened the page by the LAN address would otherwise ask ITSELF.)
   const rebased = (js: string, reqOrigin: string) =>
-    reqOrigin === origin ? js : js.split(serverUrl).join(`${reqOrigin}${base}/server`)
+    reqOrigin === origin ? js : js.split(`${origin}${base}/`).join(`${reqOrigin}${base}/`)
   const web = options.web ?? null
   const lite = options.lite ?? null
   /** A file of a built folder; the entry files revalidate — a CLI update swaps them under the same
@@ -280,7 +326,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
 
   const handle = async (req: Request, ip: string | undefined): Promise<Response> => {
     const host = req.headers.get("host")
-    const reqOrigin = host ? `http://${host}` : origin
+    const reqOrigin = host ? `${options.tls ? "https" : "http"}://${host}` : origin
     const url = new URL(req.url)
     const path = url.pathname
     // Browsers ask for it on every page load (the /web/ runner) — keep the console clean.
@@ -317,6 +363,15 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
         url.searchParams.set("dev", "..")
         return redirect(`${base}/lite/?${url.searchParams.toString()}${url.hash}`)
       }
+      if (rel === "/plugins.json") return json(200, { plugins: liteTable() })
+      const own = halves.find(({ half }) => rel.startsWith(`/plugins/${half.folder}/`))
+      if (own) {
+        const sub = rel.slice(`/plugins/${own.half.folder}/`.length)
+        if (sub === "index.js") return text(200, "text/javascript", own.js)
+        const folder = own.half.static
+        if (folder && sub.startsWith(`${folder}/`)) return built(own.half.dir, sub)
+        return text(404, "text/plain", "Not found")
+      }
       return built(lite, rel === "/" ? "index.html" : rel.slice(1))
     }
     if (route === "/version") {
@@ -372,6 +427,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
   const server = await serve({
     port: options.port,
     hostname: options.bind,
+    tls: options.tls,
     fetch: (req, peer) => handle(req, peer.ip),
     websocket: (req, peer) => {
       const path = new URL(req.url).pathname

package/src/dev/https.ts

@@ -0,0 +1,50 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/*
+ * The certificate of `lecodes web dev --https`. A phone's camera and motion sensors are given to a
+ * SECURE page only, and on the LAN that is an https one: a self-signed certificate, made once and
+ * kept in ~/.lecodes/dev-https/ — for every address it was asked for (localhost, the machine's LAN
+ * addresses), made again when one is new or when it is old. No authority signed it: the browser
+ * warns, the person accepts it once per device.
+ */
+
+const DIR = () => join(homedir(), ".lecodes", "dev-https")
+/** Days a certificate is valid: under the 398 a phone's browser accepts for a server's. */
+const DAYS = 397
+/** Made again after this many: before it runs out. */
+const RENEW_DAYS = 300
+
+type Kept = { names: string[], made: number }
+
+/** The certificate for `names` (+ localhost); `dir` is where it is kept (a test's own). */
+export const devCertificate = async (names: string[], dir = DIR()): Promise<{ cert: string, key: string }> => {
+  const files = { cert: join(dir, "cert.pem"), key: join(dir, "key.pem"), meta: join(dir, "names.json") }
+  let kept: Kept | null = null
+  try { kept = JSON.parse(readFileSync(files.meta, "utf8")) as Kept } catch { /* none yet */ }
+  const wanted = [...new Set(["localhost", "127.0.0.1", ...names])]
+  const fresh = kept && Date.now() - kept.made < RENEW_DAYS * 86_400_000 && wanted.every((n) => kept!.names.includes(n))
+  if (fresh && existsSync(files.cert) && existsSync(files.key)) {
+    return { cert: readFileSync(files.cert, "utf8"), key: readFileSync(files.key, "utf8") }
+  }
+  // (only here: the one command that asks for it loads it)
+  const { generate } = await import("selfsigned")
+  const all = [...new Set([...(kept?.names ?? []), ...wanted])]
+  const ip = /^\d{1,3}(\.\d{1,3}){3}$/
+  const made = generate([{ name: "commonName", value: "LeCodes dev" }, { name: "organizationName", value: "LeCodes dev server" }], {
+    days: DAYS, keySize: 2048, algorithm: "sha256",
+    extensions: [
+      { name: "basicConstraints", cA: false },
+      { name: "keyUsage", digitalSignature: true, keyEncipherment: true },
+      { name: "extKeyUsage", serverAuth: true },
+      // altName types of X.509: 2 = a DNS name, 7 = an IP address
+      { name: "subjectAltName", altNames: all.map((n) => (ip.test(n) ? { type: 7, ip: n } : { type: 2, value: n })) },
+    ],
+  })
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(files.cert, made.cert)
+  writeFileSync(files.key, made.private)
+  writeFileSync(files.meta, JSON.stringify({ names: all, made: Date.now() } satisfies Kept))
+  return { cert: made.cert, key: made.private }
+}

package/src/dev/serve.ts

@@ -1,5 +1,6 @@
-import { createServer, type IncomingMessage } from "node:http"
-import { Readable } from "node:stream"
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http"
+import { createServer as createHttpsServer } from "node:https"
+import { Readable, type Duplex } from "node:stream"
 import { upgradeWebSocket } from "./wsServer"
 
 /*
@@ -35,6 +36,8 @@ export type ServeOptions = {
   port: number
   /** Bind address (default 0.0.0.0). */
   hostname?: string
+  /** https (and wss) with this certificate and key, PEM. */
+  tls?: { cert: string, key: string }
   fetch: (req: Request, peer: Peer) => Response | Promise<Response>
   /** A websocket asks to connect: return what takes the open socket, or null to refuse. Decided
    *  from the request alone (its path), before the handshake. */
@@ -64,6 +67,7 @@ const serveBun = (opts: ServeOptions): Served => {
     server = Bun.serve<BunSocketData>({
       port: opts.port,
       hostname: opts.hostname ?? "0.0.0.0",
+      ...(opts.tls ? { tls: { cert: opts.tls.cert, key: opts.tls.key } } : {}),
       // seconds, the most Bun takes: an endpoint of a project's backend may think for 30
       idleTimeout: 255,
       async fetch(req, srv) {
@@ -110,33 +114,35 @@ const serveBun = (opts: ServeOptions): Served => {
 
 // ───────────────────────────── Node ─────────────────────────────
 
-const requestOf = (req: IncomingMessage, upgrade = false): Request => {
+const requestOf = (req: IncomingMessage, upgrade = false, scheme = "http"): Request => {
   const headers = new Headers()
   for (const [k, v] of Object.entries(req.headers)) {
     if (v !== undefined) headers.set(k, Array.isArray(v) ? v.join(", ") : v)
   }
   const method = req.method ?? "GET"
   const bodyless = upgrade || method === "GET" || method === "HEAD"
-  return new Request(new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`).href, {
+  return new Request(new URL(req.url ?? "/", `${scheme}://${req.headers.host ?? "localhost"}`).href, {
     method, headers,
     ...(bodyless ? {} : { body: Readable.toWeb(req), duplex: "half" }),
   } as unknown as RequestInit)
 }
 
 const serveNode = async (opts: ServeOptions): Promise<Served> => {
-  const server = createServer((req, res) => {
+  const scheme = opts.tls ? "https" : "http"
+  const onRequest = (req: IncomingMessage, res: ServerResponse) => {
     void (async () => {
       let response: Response
-      try { response = await opts.fetch(requestOf(req), { ip: req.socket.remoteAddress }) }
+      try { response = await opts.fetch(requestOf(req, false, scheme), { ip: req.socket.remoteAddress }) }
       catch (e) { response = failure(opts, e) }
       res.writeHead(response.status, Object.fromEntries(response.headers))
       if (!response.body || req.method === "HEAD") { res.end(); return }
       Readable.fromWeb(response.body as unknown as import("node:stream/web").ReadableStream).on("error", () => res.destroy()).pipe(res)
     })()
-  })
-  server.on("upgrade", (req, socket) => {
+  }
+  const server = opts.tls ? createHttpsServer({ cert: opts.tls.cert, key: opts.tls.key }, onRequest) : createServer(onRequest)
+  server.on("upgrade", (req: IncomingMessage, socket: Duplex) => {
     let accept: ((socket: Socket) => SocketHandlers) | null = null
-    try { accept = opts.websocket?.(requestOf(req, true), { ip: req.socket.remoteAddress }) ?? null }
+    try { accept = opts.websocket?.(requestOf(req, true, scheme), { ip: req.socket.remoteAddress }) ?? null }
     catch (e) { opts.onError?.(e) }
     if (!accept) { socket.destroy(); return }
     let handlers: SocketHandlers | null = null

package/src/dev/webRunner.ts

@@ -34,6 +34,8 @@ type Built = {
   sources: string[]
   /** The arguments of the `vite build` that makes it. */
   build: string[]
+  /** A command run after it in the package (a build step outside vite), when there is one. */
+  after?: string[]
 }
 
 const PLAYER: Built = {
@@ -47,10 +49,11 @@ const PAGE: Built = {
 }
 
 // Web Lite (lecodes-web-lite's dist): the app as a web page, DOM and CSS — what `lecodes web`
-// serves and builds from.
+// serves and builds from. Its plugins' halves are a step of their own after the vite build (which
+// empties dist/): build/plugins.ts writes dist/plugins/ and plugins.json from the plugin repo.
 const LITE: Built = {
-  pkg: "lecodes-web-lite", dist: "dist", entry: "lite.js", vendored: "web-lite", build: [],
-  sources: ["hosts/web-lite/src", "hosts/web-lite/index.html", "renderers/web-lite/src", "renderers/web-shared/src", "hosts/web-player/src/dev.ts", "engines/gl-lite/src"],
+  pkg: "lecodes-web-lite", dist: "dist", entry: "lite.js", vendored: "web-lite", build: [], after: ["bun", "build/plugins.ts"],
+  sources: ["hosts/web-lite/src", "hosts/web-lite/index.html", "hosts/web-lite/build", "renderers/web-lite/src", "renderers/web-shared/src", "hosts/web-player/src/dev.ts", "engines/gl-lite/src", "hosts/plugins/plugins"],
 }
 
 /** The built page of Web Lite, or null when this CLI has none. */
@@ -71,6 +74,11 @@ const resolve = (built: Built, log: (message: string) => void): string | null =>
       log(`Building ${built.pkg} (its sources are newer than its build)…`)
       const done = spawnSync("bunx", ["vite", "build", ...built.build], { cwd: checkout, stdio: "pipe", encoding: "utf8", shell: process.platform === "win32" })
       if (done.status !== 0) log(`${built.pkg} did not build — the browser gets the build that is there:\n${done.stderr || done.stdout}`)
+      else if (built.after) {
+        const [command, ...args] = built.after
+        const step = spawnSync(command!, args, { cwd: checkout, stdio: "pipe", encoding: "utf8", shell: process.platform === "win32" })
+        if (step.status !== 0) log(`${built.pkg}: \`${built.after.join(" ")}\` failed — its build is without that step:\n${step.stderr || step.stdout}`)
+      }
     }
     if (has(dist)) return dist
   }

package/src/platform/serverDiff.ts

@@ -1,9 +1,8 @@
 import { readFileSync } from "node:fs"
 import type { Project, ProjectAsset } from "./api"
 import type { LocalScan } from "../project/localFiles"
-import { classifyKind, isTextKind } from "../project/localFiles"
+import { isTextKind } from "../project/localFiles"
 import { buildPaths } from "../project/materialize"
-import { basename } from "node:path"
 
 /*
  * Compares the local working tree against the project's current server state — the basis for
@@ -49,7 +48,7 @@ export const computeServerDiff = (project: Project, scan: LocalScan): ServerDiff
     const local = localByPath.get(path)
 
     if (local && !server) {
-      const text = isTextKind(classifyKind(basename(path)))
+      const text = isTextKind(local.kind)
       entries.push({ path, status: "added", binary: !text, serverText: "", localText: text ? readFileSync(local.absPath, "utf8") : undefined })
       continue
     }

package/src/plugin/emitWeb.ts

@@ -358,18 +358,27 @@ export interface PluginGL {
   /** The pose of the scene's camera (its world matrix). */
   setCameraMatrix(scene: number, m16: ArrayLike<number>): void
   /** A projection the half computes (column-major, OpenGL clip conventions), with the near / far it
-   *  was built with, in place of the scene's fov projection. */
+   *  was built with, in place of the scene's fov projection: drawn as it is — an off-centre one (a
+   *  camera's intrinsics) too. Made for one view: a change of \`viewport\` wants a new one. */
   setProjection(scene: number, m16: ArrayLike<number>, near: number, far: number): void
   /** Back to the scene's own (fov) projection. */
   clearProjection(scene: number): void
-  /** The scene's background: a playing video behind the scene, through \`uv\` — the affine map from
-   *  the viewport's normalized coordinates (0,0 top-left) to the video's, row-major
-   *  [a, b, tx, c, d, ty] (identity by default). null = none. */
-  setBackground(scene: number, video: HTMLVideoElement | null, uv?: ArrayLike<number>): void
-  /** The web has no external textures: a video is handed to setBackground as it is. Always null. */
+  /** The scene's background, behind the scene: a playing video (a camera's stream), or a canvas the
+   *  half (or an engine it runs) draws the camera's picture on; null = none. \`uv\` = the affine map
+   *  from the viewport's normalized coordinates (0,0 top-left) to the picture's, row-major
+   *  [a, b, tx, c, d, ty] (identity by default). Web Lite shows the element itself: moved under the
+   *  scene's canvas (its inline style replaced: absolute, the scene's box filled, \`object-fit: cover\`
+   *  — \`uv\` is not read; a canvas sized to \`viewport\` × devicePixelRatio is shown 1:1), taken out of
+   *  the page when it is replaced or cleared. The web player (a preview) shows a video only. */
+  setBackground(scene: number, source: HTMLVideoElement | HTMLCanvasElement | null, uv?: ArrayLike<number>): void
+  /** The web has no external textures: a video or a canvas is handed to setBackground as it is.
+   *  Always null. */
   createExternalTexture(): null
-  /** \`body\` before each frame (the page's animation frame), until the returned function is called —
-   *  or the world swap. */
+  /** \`body\` before each frame of the 3D engine, until the returned function is called — or the
+   *  world swap: in the host's own animation frame, before the tick and the render, so what a body
+   *  sets (a pose, a projection) is that frame's picture. A requestAnimationFrame callback of the
+   *  half's own is a frame late unless the browser runs it before the host's (callbacks run in the
+   *  order they were asked for). Web Lite runs the bodies while a scene is on show. */
   onFrame(body: () => void): () => void
   /** The composite of the scene's next frame — the 3D picture, not the UI over it: RGBA8, top row
    *  first, width, height; null (0 × 0) when the scene is not the one presented. */

package/src/plugin/firstParty.ts

@@ -0,0 +1,30 @@
+// The first-party plugins as the SDK carries them: `plugins/gen/<id>/` of its source tree — the
+// contract.d.ts and the app's wrapper (sdk/), copies of the plugin repo's (core's
+// scripts/vendor-plugins.ts). A project's HALF FOLDER (`implements` in its manifest) implements one
+// of these contracts: the one of the SDK this CLI compiles with, so the glue `lecodes plugin gen`
+// writes for the half and the wrapper in the bundle are of one contract.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+import { sdkSourceDir } from "../compile/projectCompile"
+
+const ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+
+/** The SDK's copy of a first-party plugin's contract, or null when the SDK carries no such plugin. */
+export const firstPartyContractFile = (id: string): string | null => {
+  if (!sdkSourceDir || !ID.test(id)) return null
+  const file = join(sdkSourceDir, "plugins", "gen", id, "contract.d.ts")
+  return existsSync(file) ? file : null
+}
+
+/** The first-party plugins the SDK carries, by id. */
+export const firstPartyIds = (): string[] => {
+  if (!sdkSourceDir) return []
+  const gen = join(sdkSourceDir, "plugins", "gen")
+  return existsSync(gen) ? readdirSync(gen).filter((id) => existsSync(join(gen, id, "contract.d.ts"))).sort() : []
+}
+
+/** A copy's text as the plugin wrote it: the vendoring points the import of the SDK at its own file
+ *  (`../../../plugin`), a contract reads `lecodes-sdk/plugin` and nothing else. */
+export const firstPartyContractText = (file: string): string =>
+  readFileSync(file, "utf8").replace(/from "(?:\.\.\/)+plugin"/g, `from "lecodes-sdk/plugin"`)

package/src/plugin/generate.ts

@@ -16,7 +16,8 @@ import { EmitError, emitSdk } from "./emitSdk"
 import { emitSwift } from "./emitSwift"
 import { emitWeb } from "./emitWeb"
 import { lower } from "./lower"
-import { MANIFEST_FILE, ManifestError, readManifestIfAny, type PluginManifest } from "./manifest"
+import { CONTRACT_FILE, MANIFEST_FILE, ManifestError, readManifestIfAny, type PluginManifest } from "./manifest"
+import { firstPartyContractFile, firstPartyContractText } from "./firstParty"
 import { missingDeclarations, usesFeatures, usesPermissions, type PermissionKind } from "./permissions"
 import { DEFAULT_SDK_PATH, PACKAGE_FILE, PackageError, emitPackageSwift } from "./emitPackage"
 
@@ -24,19 +25,31 @@ import { DEFAULT_SDK_PATH, PACKAGE_FILE, PackageError, emitPackageSwift } from "
 // compared and pasted; `\` is Windows' own).
 const shown = (from: string, to: string): string => relative(from, to).split(sep).join("/")
 
-export const CONTRACT_FILE = "contract.d.ts"
+export { CONTRACT_FILE }
 
 export type PluginDir = { id: string, dir: string }
 
-/** The plugins under `path`: itself when it holds a contract, else every `plugins/<id>/` that does. */
+/** The first-party plugin a folder's manifest says it implements (a project's half folder), or null.
+ *  Read loosely: what the manifest holds is readManifest's to say. */
+const implementsOf = (dir: string): string | null => {
+  try {
+    const raw = JSON.parse(readFileSync(join(dir, MANIFEST_FILE), "utf8").replace(/^/, "")) as { implements?: unknown }
+    return typeof raw.implements === "string" ? raw.implements : null
+  } catch { return null }
+}
+
+/** A plugin's folder: one with its contract, or a half folder that implements a first-party one's. */
+const isPluginDir = (dir: string): boolean => existsSync(join(dir, CONTRACT_FILE)) || implementsOf(dir) !== null
+
+/** The plugins under `path`: itself when it is one, else every `plugins/<id>/` that is. */
 export const findPlugins = (path: string): PluginDir[] => {
   const root = resolve(path)
-  if (existsSync(join(root, CONTRACT_FILE))) return [{ id: basename(root), dir: root }]
+  if (isPluginDir(root)) return [{ id: basename(root), dir: root }]
   const holder = join(root, "plugins")
   if (!existsSync(holder)) return []
   return readdirSync(holder).sort()
     .map(id => ({ id, dir: join(holder, id) }))
-    .filter(p => statSync(p.dir).isDirectory() && existsSync(join(p.dir, CONTRACT_FILE)))
+    .filter(p => statSync(p.dir).isDirectory() && isPluginDir(p.dir))
 }
 
 /** The CLI carries no TypeScript: a contract is read with the one its author has — the plugin's own
@@ -54,34 +67,39 @@ export const loadTypescript = (dir: string): typeof tsModule => {
 
 export type Generated = { file: string, text: string }
 
-/** Everything one plugin's contract generates, as `path → text`. Throws ContractError / EmitError. */
+/** Everything one plugin's contract generates, as `path → text`. Throws ContractError / EmitError /
+ *  ManifestError. A half folder (`implements`) is generated from the contract of the plugin it
+ *  implements, the SDK's copy (firstParty.ts), and under that plugin's id: `web/ar.gen.ts` registers
+ *  the service "ar"; it has no sdk/ — the app's side is the SDK's wrapper. */
 export const generatePlugin = (ts: typeof tsModule, plugin: PluginDir): { contract: Contract, manifest: PluginManifest | null, files: Generated[] } => {
-  const file = join(plugin.dir, CONTRACT_FILE)
-  const contract = readContract(ts, file, readFileSync(file, "utf8"))
   // The manifest is held to the folders the plugin has: a half the manifest does not name is built
   // into no host.
   const manifest = readManifestIfAny(plugin.dir, plugin.id)
+  const implemented = manifest?.implements
+  const file = implemented ? firstPartyContractFile(implemented)! : join(plugin.dir, CONTRACT_FILE)
+  const contract = readContract(ts, file, implemented ? firstPartyContractText(file) : readFileSync(file, "utf8"))
   checkPermissions(plugin, contract, manifest)
-  const handWritten = existsSync(join(plugin.dir, "sdk", `${plugin.id}.ts`))
+  const id = implemented ?? plugin.id
+  const handWritten = existsSync(join(plugin.dir, "sdk", `${id}.ts`))
   const single = contract.channels.length === 1
-  const files: Generated[] = contract.channels.map(channel => ({
+  const files: Generated[] = implemented ? [] : contract.channels.map(channel => ({
     // One channel is the rule; a contract with several names each file after its channel.
-    file: join(plugin.dir, "sdk", single ? `${plugin.id}.gen.ts` : `${plugin.id}.${channel.iface}.gen.ts`),
-    text: emitSdk(contract, channel, { id: plugin.id, handWritten }),
+    file: join(plugin.dir, "sdk", single ? `${id}.gen.ts` : `${id}.${channel.iface}.gen.ts`),
+    text: emitSdk(contract, channel, { id, handWritten }),
   }))
   // A platform's file is generated where its FOLDER exists: the plugin says which platforms it has
   // by having them.
   if (existsSync(join(plugin.dir, "ios"))) {
     const name = single ? contract.channels[0]!.iface : contract.channels[0]!.iface + "Plugin"
-    files.push({ file: join(plugin.dir, "ios", `${name}.gen.swift`), text: emitSwift(lower(contract), { id: plugin.id }) })
+    files.push({ file: join(plugin.dir, "ios", `${name}.gen.swift`), text: emitSwift(lower(contract), { id }) })
   }
   if (existsSync(join(plugin.dir, "android"))) {
     const name = single ? contract.channels[0]!.iface : contract.channels[0]!.iface + "Plugin"
     const pkg = kotlinPackage(join(plugin.dir, "android"))
-    files.push({ file: join(pkg.dir, `${name}.gen.kt`), text: emitKotlin(lower(contract), { id: plugin.id, package: pkg.name }) })
+    files.push({ file: join(pkg.dir, `${name}.gen.kt`), text: emitKotlin(lower(contract), { id, package: pkg.name }) })
   }
   if (existsSync(join(plugin.dir, "web"))) {
-    files.push({ file: join(plugin.dir, "web", `${plugin.id}.gen.ts`), text: emitWeb(lower(contract), { id: plugin.id }) })
+    files.push({ file: join(plugin.dir, "web", `${id}.gen.ts`), text: emitWeb(lower(contract), { id }) })
     const foreign = hostImports(join(plugin.dir, "web"))
     if (foreign.length) throw new EmitError(`web/ imports the host — a web half depends on its generated file, the document it is handed and the browser:\n${foreign.map(f => `  ${f}`).join("\n")}`)
   }
@@ -164,7 +182,8 @@ export const repoSdkPath = (root: string): string => {
 }
 
 export type GenReport = {
-  plugins: { id: string, contract: Contract, written: string[], stale: string[], fresh: string[] }[]
+  /** `implements`: a half folder's first-party plugin, whose contract it was generated from. */
+  plugins: { id: string, implements?: string, contract: Contract, written: string[], stale: string[], fresh: string[] }[]
   /** The repo's own files (its Package.swift), when the path is a repo of plugins. */
   repo: { written: string[], stale: string[], fresh: string[] }
   /** Contracts that did not read or emit, as printable text. */
@@ -175,7 +194,7 @@ export type GenReport = {
  *  to `path`. A failed contract does not stop the others. */
 export const generate = (path: string, opts: { check?: boolean } = {}): GenReport => {
   const plugins = findPlugins(path)
-  if (plugins.length === 0) throw new CliError(`No plugin under ${resolve(path)}: a plugin is a directory with a ${CONTRACT_FILE} (one, or plugins/<id>/ of a repo).`)
+  if (plugins.length === 0) throw new CliError(`No plugin under ${resolve(path)}: a plugin is a directory with a ${CONTRACT_FILE}, or a half folder whose ${MANIFEST_FILE} says what it \`implements\` (one, or plugins/<id>/ of a repo or a project).`)
   const ts = loadTypescript(plugins[0]!.dir)
   const root = resolve(path)
   const report: GenReport = { plugins: [], repo: { written: [], stale: [], fresh: [] }, failures: [] }
@@ -194,7 +213,7 @@ export const generate = (path: string, opts: { check?: boolean } = {}): GenRepor
     try {
       const { contract, manifest, files } = generatePlugin(ts, plugin)
       if (manifest) manifests.push({ id: plugin.id, manifest })
-      const entry = { id: plugin.id, contract, written: [] as string[], stale: [] as string[], fresh: [] as string[] }
+      const entry = { id: plugin.id, implements: manifest?.implements, contract, written: [] as string[], stale: [] as string[], fresh: [] as string[] }
       for (const f of files) place(f, entry)
       report.plugins.push(entry)
     } catch (e) {
@@ -206,9 +225,10 @@ export const generate = (path: string, opts: { check?: boolean } = {}): GenRepor
   }
 
   // A repo of plugins (not one plugin): its Package.swift, from every manifest that read. Written
-  // only when every contract made it — a repo with a broken plugin keeps the package it has.
-  const isRepo = !existsSync(join(root, CONTRACT_FILE))
-  if (isRepo && report.failures.length === 0 && manifests.some(m => m.manifest.ios)) {
+  // only when every contract made it — a repo with a broken plugin keeps the package it has — and
+  // only when one has an iOS half: a project whose plugins are web halves has no package to make.
+  const isRepo = !(plugins.length === 1 && plugins[0]!.dir === root)
+  if (isRepo && report.failures.length === 0 && manifests.some(m => m.manifest.ios !== null)) {
     try {
       place({ file: join(root, PACKAGE_FILE), text: emitPackageSwift(manifests, repoSdkPath(root)) }, report.repo)
     } catch (e) {

package/src/plugin/manifest.ts

@@ -9,11 +9,18 @@
 //
 // Desktop plugins are another system (a prebuilt library behind a C ABI) with a manifest of their
 // own shape; nothing of it is read here.
+//
+// A HALF FOLDER of a project (`implements: "<first-party id>"`) has no contract and no sdk/ of its
+// own: it implements the contract of a first-party plugin the SDK carries, for the platforms it has
+// a half of — app.json names it for those (`"ar": { "web": "./plugins/ar-8thwall" }`), the
+// first-party halves stay everywhere else.
 
 import { existsSync, readFileSync, statSync } from "node:fs"
-import { join } from "node:path"
+import { isAbsolute, join } from "node:path"
+import { firstPartyContractFile, firstPartyIds } from "./firstParty"
 
 export const MANIFEST_FILE = "lecodes-plugin.json"
+export const CONTRACT_FILE = "contract.d.ts"
 
 /** A SwiftPM dependency the iOS half links. */
 export type IosPackage = { url: string, exact?: string, from?: string, products: string[] }
@@ -30,6 +37,9 @@ export type PluginManifest = {
    *  contract between a bundle, the runtime and a half. */
   sdk: string
   description?: string
+  /** A HALF FOLDER: the first-party plugin whose contract the folder implements (it has no
+   *  contract.d.ts and no sdk/ of its own — the app's side is the SDK's wrapper). */
+  implements?: string
   ios: {
     /** The Swift module the half is built as in a shell. Default: `LeCodes` + the id in PascalCase. */
     module?: string
@@ -56,6 +66,11 @@ export type PluginManifest = {
     dependencies?: Record<string, string>
     /** The half's bundler resources, by the name `register` receives them under. */
     resources?: Record<string, WebResource>
+    /** A folder of the plugin (relative to it) put beside the built module AS IS, names unhashed: a
+     *  runtime the half loads by its own url (`new URL("<static>/x.js", import.meta.url)`), which
+     *  fetches its files relative to itself. A project's half; the first-party halves are built in
+     *  Web Lite's page with `resources`. */
+    static?: string
   } | null
 }
 
@@ -69,7 +84,7 @@ const ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
 const VERSION = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/
 const RANGE = /^[\^~]?\d+\.\d+\.\d+$/
 const PLATFORMS = ["ios", "android", "web"] as const
-const KNOWN = new Set(["id", "name", "version", "sdk", "description", ...PLATFORMS])
+const KNOWN = new Set(["id", "name", "version", "sdk", "description", "implements", ...PLATFORMS])
 const GONE: Record<string, string> = {
   provides: "the channels are the contract's (contract.d.ts)",
   js: "the wrapper is found by convention (sdk/)",
@@ -78,7 +93,7 @@ const GONE: Record<string, string> = {
 const BRANCH: Record<(typeof PLATFORMS)[number], Set<string>> = {
   ios: new Set(["module", "register", "infoPlist", "entitlements", "packages"]),
   android: new Set(["module", "register", "dependencies", "gradlePlugins"]),
-  web: new Set(["register", "dependencies", "resources"]),
+  web: new Set(["register", "dependencies", "resources", "static"]),
 }
 
 const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
@@ -116,6 +131,13 @@ export const readManifest = (dir: string, id: string): PluginManifest => {
   const sdk = text("sdk")
   if (sdk !== undefined && !RANGE.test(sdk)) problems.push(`sdk: "${sdk}" — a range of the SDK's version: ^2.0.0`)
   if (raw.description !== undefined && typeof raw.description !== "string") problems.push("description: a text")
+  if (raw.implements !== undefined) {
+    const impl = raw.implements
+    if (typeof impl !== "string" || !ID.test(impl)) problems.push(`implements: the id of the first-party plugin whose contract the folder implements ("ar")`)
+    else if (!firstPartyContractFile(impl)) problems.push(`implements: "${impl}" is no first-party plugin of this SDK (${firstPartyIds().join(", ") || "it carries none"})`)
+    if (existsSync(join(dir, CONTRACT_FILE))) problems.push(`implements: the folder implements another plugin's contract — it has no ${CONTRACT_FILE} of its own`)
+    if (isFolder(join(dir, "sdk"))) problems.push("implements: the folder implements another plugin — its app side is the SDK's, it has no sdk/ of its own")
+  }
 
   for (const platform of PLATFORMS) {
     const branch = raw[platform]
@@ -181,6 +203,14 @@ export const readManifest = (dir: string, id: string): PluginManifest => {
         }
       }
     }
+    const folder = web.static
+    if (folder !== undefined) {
+      const segments = typeof folder === "string" ? folder.split(/[\\/]/) : []
+      if (typeof folder !== "string" || folder.trim() === "" || isAbsolute(folder) || segments.some((s) => s === ".." || s === "." || s === "")) {
+        problems.push(`web.static: a folder of the plugin, by its path in it ("xr-runtime")`)
+      } else if (!isFolder(join(dir, folder))) problems.push(`web.static: ${folder} is not a folder of the plugin`)
+      else if (folder === "index.js") problems.push(`web.static: "index.js" is the built module's name`)
+    }
   }
 
   if (problems.length) throw new ManifestError(file, problems)