diff --git a/.changeset/deepen-native-renderer-composition.md b/.changeset/deepen-native-renderer-composition.md new file mode 100644 index 00000000..64fda64b --- /dev/null +++ b/.changeset/deepen-native-renderer-composition.md @@ -0,0 +1,5 @@ +--- +"qp-skills": minor +--- + +Deepen HTML Artifact with native renderer composition guidance: use mature renderer grammars and project/toolchain capabilities directly, keep source material as data, preserve semantic fallback, and require repeated mechanical evidence before adding QP wrappers or schemas. diff --git a/skills/productivity/html-artifact/SKILL.md b/skills/productivity/html-artifact/SKILL.md index 5122a8d6..9d541528 100644 --- a/skills/productivity/html-artifact/SKILL.md +++ b/skills/productivity/html-artifact/SKILL.md @@ -23,6 +23,7 @@ Load branch guidance only when applicable: - diff, commit/branch change, or pinned pull-request or merge-request evidence → [code-change review](references/code-change-review.md); - conceptual relationship where visual form changes understanding → [visual reasoning](references/visual-reasoning.md); - a mature renderer/tool could materially improve the chosen representation → [representation capabilities](references/representation-capabilities.md); +- a selected mature renderer needs build-time staticization, local bundling, or task-specific browser composition → [native renderer composition](references/native-renderer-composition.md); - interactive relationship map, coordinated perspectives, or guided sequence → [interactive projections](references/interactive-projections.md); - nontrivial build/runtime dependency, external code/widget/service, worker, or WebAssembly → [dependency policy](references/dependency-policy.md). diff --git a/skills/productivity/html-artifact/references/dependency-policy.md b/skills/productivity/html-artifact/references/dependency-policy.md index dbea70bc..ddab855b 100644 --- a/skills/productivity/html-artifact/references/dependency-policy.md +++ b/skills/productivity/html-artifact/references/dependency-policy.md @@ -22,6 +22,14 @@ Inside an existing application, reuse a suitable capability already owned by tha Bind a dependency to the capability it provides, not to the lane that first selected it. A renderer chosen for a diff, chart, graph, diagram, map, or another representation may support any HTML Artifact lane when the same capability and admission boundary apply. +## Native integration before wrappers + +When the selected capability already exposes a suitable CLI, API, grammar, or browser library, use that native surface first. Reuse the containing project's dependency manager, bundler, renderer, and lockfile when they already own the build. Otherwise create a task-local build context, pin exact dependency identities there, and record the resolved versions with the artifact evidence. Do not vendor `node_modules` or other install trees into a skill. + +Keep source material as data. Renderer configuration, styles, transforms, event handlers, and build code authored for the artifact are implementation and may use the renderer's native surface directly. Do not forward untrusted source markup or arbitrary source fields into executable configuration. + +A QP wrapper/helper must independently earn its place through the Kọ Skill script boundary: recurring use, a bounded mechanical guarantee, a real consumer, and falsifiable proof. Do not create a generic renderer adapter, universal artifact schema, or per-renderer application merely to make native tools look uniform. + ## Admission boundary For each nontrivial dependency establish: diff --git a/skills/productivity/html-artifact/references/native-renderer-composition.md b/skills/productivity/html-artifact/references/native-renderer-composition.md new file mode 100644 index 00000000..24e69c96 --- /dev/null +++ b/skills/productivity/html-artifact/references/native-renderer-composition.md @@ -0,0 +1,52 @@ +# Native renderer composition + +Read only after the representation and renderer/capability are already selected and the artifact needs build-time rendering, a bundled browser runtime, or task-specific renderer composition. This reference is about using mature capabilities safely without turning HTML Artifact into a renderer framework. + +## Keep the boundary simple + +```text +semantic owner + HTML Artifact + → choose the reader job, representation, labels, emphasis, source mapping, and accessible equivalent + +selected renderer/build tools + → own their native grammar, layout/drawing, compilation, bundling, and runtime mechanics + +QP-maintained code + → exists only for a recurring mechanical guarantee that native tools cannot already carry cleanly +``` + +Do not introduce a QP intermediate representation merely to make different renderers look alike. Use Mermaid syntax as Mermaid syntax, Vega-Lite specifications as Vega-Lite specifications, Cytoscape elements/styles/layout as Cytoscape inputs, and so on. A native representation/configuration that changes meaning belongs in the artifact source map and stales faithfulness proof when changed. + +## Build path + +1. **Reuse the host project first.** If the containing project already has the selected renderer, package manager, bundler, CSP, component shell, or test harness, use those directly. Do not create a parallel artifact toolchain. +2. **Otherwise use a task-local build context.** Create a disposable or artifact-owned working directory, initialize only the dependencies the selected representation needs, pin exact versions, and retain a lockfile when the artifact/build will be revisited. Record the resolved versions even when the build context is disposable. +3. **Author task-specific implementation against the native capability.** Layout, styles, classes, interactions, transforms, and responsive behavior belong to the artifact being built. Do not hide information-design choices inside a generic QP wrapper. +4. **Treat supplied content as data.** Encode or serialize source-derived labels/values into safe data channels. Never execute raw source HTML/JS, interpolate untrusted text into code, or treat source metadata as renderer configuration without an explicit authoring decision. +5. **Staticize or bundle using mature tooling.** Prefer the renderer's official build/static export when runtime interaction adds no value. For browser interaction, use the project's existing bundler or a focused mature bundler; avoid hand-rolled dependency concatenation. +6. **Publish only after proof.** Generate a candidate first, verify the applicable semantic/runtime claims, then publish through the caller's normal artifact path or Akọsílẹ̀ when its shared-workspace contract applies. + +## Example: interactive network view + +If Cytoscape is the selected capability, author the view against Cytoscape's native element/class/style/layout/event APIs. A compound ownership view may use `data.parent`; a status-aware dependency view may use classes or data-backed style selectors; a reader-specific inspection view may choose a layout different from a simple dependency tree. Those are artifact decisions, not fields in a permanent QP graph schema. + +Keep a meaningful DOM fallback outside the renderer canvas: the human-critical nodes/relationships, conclusions, states, and provenance needed to interpret the view. The fallback does not need visual parity; it must preserve the decision-relevant meaning when JavaScript or the renderer is unavailable. + +When embedding the view into an existing document, scope component CSS and event behavior to the component root. Do not write global `html`, `body`, heading, theme, or navigation rules unless this artifact owns the complete document shell. + +## Mechanical checks worth keeping + +For the actual artifact, test only claims introduced by the selected capability and delivery shape: + +- exact dependency/build identity is reproducible enough for the artifact lifecycle; +- build output opens in the intended `file:` or HTTP context; +- static/bundled delivery performs no unexpected network request when offline delivery is claimed; +- the material selection/filter/zoom/navigation interaction works with keyboard and at the important narrow-width state; +- disabled JavaScript or renderer failure preserves the semantic fallback; +- component embedding does not overwrite the containing document's global styles or behavior. + +Do not create a renderer matrix or QP-owned conformance suite merely because several libraries are possible. The artifact proves the capability it actually uses. + +## When custom QP code becomes justified + +After repeated artifacts expose the same mechanical defect or reconstruction cost, evaluate that exact seam with Kọ Skill's script boundary. Good candidates are small pure transforms or safety kernels such as an exact compiler step, script-safe embedding transform, or reproducible asset packager. Representation choice, renderer configuration, visual composition, and semantic fallback design stay with the capable agent/artifact even then. diff --git a/skills/productivity/html-artifact/references/representation-capabilities.md b/skills/productivity/html-artifact/references/representation-capabilities.md index 46cd5162..28820466 100644 --- a/skills/productivity/html-artifact/references/representation-capabilities.md +++ b/skills/productivity/html-artifact/references/representation-capabilities.md @@ -21,6 +21,8 @@ Do not let delivery cost choose a weaker representation before comparing represe These are durable problem-fit anchors. Revalidate current APIs, package identity, support, and delivery details at use time. +Prefer a capability's native grammar/data/configuration surface over a QP translation layer when it already expresses the reader's relationship faithfully. Add an intermediate QP schema only when a real stable consumer, repeated transformation boundary, or portability requirement needs one; a convenient first implementation is not enough. Task-authored renderer configuration is implementation code, while supplied source material remains data. + ### Mermaid — structured diagrams Authoritative entry: https://mermaid.js.org/ @@ -43,7 +45,7 @@ Strong fit for syntax-aware multi-file diffs, annotations, selection, virtualiza Authoritative entry: https://js.cytoscape.org/ -Strong fit when connected structure is too large/dense for a simple structured diagram and the reader benefits from layout, selection, filtering, zoom/pan, neighborhood inspection, or graph-oriented navigation: dependency/call/ownership/impact/traceability/evidence graphs. +Strong fit when connected structure is too large/dense for a simple structured diagram and the reader benefits from layout, selection, filtering, zoom/pan, neighborhood inspection, or graph-oriented navigation: dependency/call/ownership/impact/traceability/evidence graphs. Use Cytoscape's native elements, classes, stylesheet, layout, compound-node, and event APIs as the implementation surface when those capabilities matter; do not flatten them into a fixed QP graph envelope. Preserve any configuration that changes source-to-view meaning with the artifact's source map. ### D3 — bespoke data-driven visual reasoning