ggaction 0.0.9 → 0.0.10

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `ggaction` are recorded in this file.
 
 ## Unreleased
 
+## [0.0.10] - 2026-08-11
+
+### Added
+
+- Added collision-safe import-time extension registration through
+  `registerExtension({ name, actions })`, including strict TypeScript module
+  augmentation for registered actions on the standard `chart()` program.
+- Added installed extension-authoring knowledge that guides LLM agents through
+  feature-first design, current ggaction reuse, lifecycle ownership, primitive
+  parity, and package-consumer verification.
+
+### Changed
+
+- Updated extension documentation and examples to make installable packages
+  compose through registration while retaining `ChartProgram` subclasses for
+  deliberately isolated programs.
+
 ## [0.0.9] - 2026-08-10
 
 ### Added
@@ -197,6 +214,7 @@ All notable changes to `ggaction` are recorded in this file.
 - Cartesian charts are the complete current path. Polar semantic tokens exist only where explicitly documented and do
   not imply complete polar rendering.
 
+[0.0.10]: https://github.com/ggaction/ggaction/releases/tag/v0.0.10
 [0.0.9]: https://github.com/ggaction/ggaction/releases/tag/v0.0.9
 [0.0.8]: https://github.com/ggaction/ggaction/releases/tag/v0.0.8
 [0.0.7]: https://github.com/ggaction/ggaction/releases/tag/v0.0.7

package/README.md

@@ -198,7 +198,7 @@ The package is ESM-only and requires Node.js 20 or later.
 | --- | --- |
 | `ggaction` | Create chart programs and render them to Browser Canvas |
 | `ggaction/basic` | Create and render scatter, line, bar, histogram, and heatmap charts with a smaller browser bundle |
-| `ggaction/extension` | Author wrapped actions with public low-level primitives |
+| `ggaction/extension` | Author and register wrapped actions with public low-level primitives |
 | `ggaction/png` | Render a completed program to a PNG file in Node.js |
 | `ggaction/pdf` | Render a completed program to a single-page vector PDF file in Node.js |
 | `ggaction/svg` | Serialize a completed program to browser-safe SVG |
@@ -229,7 +229,7 @@ the extra discussion required before public API or architecture changes.
 
 ## Status and development
 
-> **Status:** `0.0.9` is the current experimental public release. APIs may change before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
+> **Status:** `0.0.10` is the current experimental public release. APIs may change before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
 
 ```bash
 npm install

package/knowledge/extension-authoring.md

@@ -0,0 +1,248 @@
+# Extension Authoring Knowledge
+
+## Purpose and authority
+
+This is the compact, installed guide for LLM agents that build extension
+packages against this copy of ggaction. It is ordinary package knowledge, not
+an `AGENTS.md` file, so an extension repository must explicitly tell its agent
+to read it.
+
+Use the version in [`package.json`](../package.json) as the compatibility
+baseline. For exact current behavior, the installed runtime and declarations
+take precedence over this guide. Do not substitute behavior from the mutable
+GitHub default branch, a roadmap, or a different installed version.
+
+## Minimum intake
+
+Before proposing or implementing an extension action:
+
+1. Read [`types/extension.d.ts`](../types/extension.d.ts) and
+   [`src/extension.js`](../src/extension.js) to confirm the installed public
+   extension entry point.
+2. Search [`action-cards.json`](./action-cards.json) for actions whose names,
+   intents, owned resources, or prerequisites overlap the requested feature.
+   Read only relevant cards instead of loading the complete catalog into the
+   working context.
+3. Inspect the installed declaration and source for each reuse candidate when
+   the action card does not settle a signature, default, error, ownership, or
+   interaction question.
+4. Record in the extension specification which ggaction actions are reused,
+   which domain behavior remains new, and the installed ggaction version used
+   for that decision.
+
+[`task-resolver.js`](./task-resolver.js) may help decompose a concrete chart
+request into current built-in actions. Its result is chart-authoring guidance,
+not authority for extension APIs or unsupported core behavior.
+
+## Design from the feature, then the actions
+
+Start with the visualization the extension must make possible and its accepted
+data. Derive action boundaries only after that feature contract is clear.
+
+- Reuse a current public action when it already owns the required behavior.
+- Compose public domain actions for existing chart resources instead of
+  recreating their scale, guide, layout, mark, transform, or renderer logic.
+- Add an extension action only for domain behavior that current actions cannot
+  express coherently.
+- Use extension primitives only inside a domain action that owns the resulting
+  semantic and graphical lifecycle. Primitives are not a replacement chart
+  authoring surface.
+- Never call private helpers or internal wrapped actions from an extension.
+- Require an explicit resource ID when existing state does not identify one
+  unique dataset, mark, scale, coordinate, guide, or graphic.
+
+## Freeze the executable design before code
+
+Before implementation, record one complete vertical slice in the extension
+specification:
+
+- the accepted input forms, canonical domain representation, and deterministic
+  conversions between them;
+- the shortest complete public program that demonstrates the feature;
+- an ordered action hierarchy that distinguishes reused public actions from new
+  extension actions and records conditional children;
+- the canonical owner of every semantic value, derived resource, and graphic;
+  and
+- the expected create, repeat, edit, remove, data-change, and relevant
+  Canvas/scale lifecycle.
+
+Do not begin dependent implementation while the slice still requires an
+unresolved core primitive, renderer capability, semantic path, ownership rule,
+or composition mechanism. Keep that requirement as an explicit upstream
+decision instead of inventing a local substitute.
+
+## Composition and ownership
+
+A high-level extension action must call a reusable public action when that
+action owns the required validation, inference, state, or materialization. Do
+not flatten an action hierarchy into copied validators, name matching, or
+parallel state updates. The parent should remain thin and its meaningful child
+calls should appear in deterministic trace order.
+
+Give each capability one canonical resolver and one canonical state owner.
+Store requested, inferred, and default values where downstream consumers can
+trace them; do not duplicate the same semantic fact in several resources.
+Omitted targets may resolve only from an explicit current owner or one unique
+compatible owner. Missing and ambiguous ownership are different errors, and
+neither permits selecting the first candidate.
+
+Type-checking an action hierarchy is not runtime closure. Exercise the complete
+program with representative data so that every prerequisite, target, derived
+resource, guide, and renderer route is real and connected.
+
+## Core model
+
+- `ChartProgram` is immutable. Return a new program and preserve earlier
+  programs and caller-owned input.
+- `semanticSpec` records chart meaning. Fully materialized, backend-neutral
+  `graphicSpec` records concrete output.
+- A semantic edit does not compile into graphics automatically. The owning
+  domain action must invoke every graphical operation required by its semantic
+  change.
+- Renderers consume `graphicSpec`; extension state must not contain
+  renderer-specific objects or commands.
+- A user-visible extension action should form one meaningful trace subtree.
+  Lower-level wrapped calls belong beneath it.
+
+## Lifecycle and atomic failure
+
+Validate a normalized complete candidate and every affected downstream
+consumer before returning the first changed program. A rejected action must
+preserve the earlier program, trace, semantic and graphic state, caller-owned
+options, and source rows.
+
+When a supported semantic revision changes graphical output, the owning action
+must rebind every affected consumer, rematerialize each required resource once,
+and remove only resources that are truly orphaned. Repeated calls must not
+accumulate geometry, duplicate resources, or revive state removed by an earlier
+action. Removal must clear owned semantic, graphic, guide, selection, highlight,
+and convenience context that would otherwise become stale.
+
+If the public extension boundary cannot express a required rebind,
+rematerialization, or safe release, stop at the upstream decision boundary.
+Do not reproduce private lifecycle machinery inside the extension.
+
+## Primitive oracle and visual acceptance
+
+For new visual behavior, first build one readable primitive baseline. Reuse
+existing public data, mark, encoding, scale, guide, layout, and renderer actions;
+use extension primitives only for the behavior that is genuinely missing.
+Keep pure geometry or statistical expectations in an independent literal
+oracle rather than copying the production implementation.
+
+The final public extension program and its primitive baseline must converge on
+the same semantic result, concrete `graphicSpec`, drawing order, and applicable
+renderer calls. For one representative contract, compare decoded pixels when
+the renderer permits deterministic raster evidence. A renderer completing
+without throwing is not sufficient: also assert item cardinality, finite
+geometry, topology, bounds, clipping, and value-to-geometry invariants.
+
+When a feature introduces a new appearance or layout, treat representative
+visual review as a separate acceptance gate. Structural tests cannot decide
+whether spacing, alignment, hierarchy, or readability matches the intended
+visual contract.
+
+## Current action-authoring boundary
+
+Import `action` and `registerExtension` from `ggaction/extension`. An installable
+extension package defines all methods with `action()` and calls
+`registerExtension({ name, actions })` once when its entry module is imported.
+The package must mark that entry as a side effect so bundlers preserve the
+registration import.
+
+Registration adds actions only to the complete `chart()` program from
+`ggaction`; it never changes `ggaction/basic`. Each action key must equal the
+wrapped action's `op`. Extension names, built-in and internal program names, and
+previously registered action names cannot collide. The complete action map is
+validated before any method is installed, and non-conflicting extension
+packages must work in either import order.
+
+Every wrapped action:
+
+- has a stable, non-empty `op` and `description`;
+- accepts one plain options object;
+- runs with the entered immutable program as `this`;
+- returns an instance of the same `ChartProgram` subclass; and
+- leaves a successful result with an empty action stack.
+
+For strict TypeScript, augment `RegisteredExtensionActions` in the
+`ggaction/extension` module with each property typed as its exact wrapped action.
+Confirm the exact generic and return types in the installed
+[`types/extension.d.ts`](../types/extension.d.ts) instead of copying a signature
+from another version.
+
+`ChartProgram` remains available for deliberately isolated local subclasses.
+Do not mutate its shared prototype directly; installable packages use
+`registerExtension()` so registration is checked and composable.
+
+The low-level primitives available through `ChartProgram` are:
+
+- `editSemantic` for a supported semantic path;
+- `createGraphics` for backend-neutral graphic identity and hierarchy; and
+- `editGraphics` for concrete graphic values or removal.
+
+Use the installed declarations and validation behavior to determine supported
+paths, graphic types, properties, and values. Do not invent opaque semantic
+branches, graphic properties, renderer instructions, or automatic
+materialization.
+
+## Upstream decision boundary
+
+Stop extension implementation and propose a ggaction core change when the
+feature requires any of the following:
+
+- a semantic path or persisted value the installed core rejects;
+- a new shared graphic primitive or renderer capability;
+- access to a private or internal action;
+- a change to immutable state, trace, materialization, or renderer boundaries;
+- a change to the public extension registration or composition mechanism; or
+- behavior that would be duplicated inconsistently across extensions.
+
+Keep that core proposal separate from the extension implementation. Do not hide
+the missing core contract behind monkey-patching, source-relative imports,
+renderer-specific state, or copied internal code.
+
+## LLM working discipline
+
+- Read the installed compact knowledge needed for the current feature; do not
+  preload complete documentation or copy rules from historical roadmaps.
+- When using the task resolver, submit only the exact user request. Do not add
+  dataset contents or code scaffolding to the query.
+- Make specifications and examples executable without guesswork: include exact
+  public imports, program construction, data and Canvas prerequisites,
+  immutable chaining or reassignment, and the requested renderer call.
+- Treat a known unsupported capability as terminal. Keep a decision that needs
+  user input or a bounded reference read explicitly unresolved; never hide
+  either case behind a nearby action or silent partial output.
+- Keep failure feedback bounded and actionable. Preserve the original failure
+  category while reporting the smallest public correction path.
+
+## Required evidence
+
+For each new public extension action, verify at least:
+
+- the public package entry works from an installed-package consumer;
+- importing the package registers every declared action on `chart()` but not
+  `ggaction/basic`;
+- registration rejects collisions and invalid batches without partial changes,
+  and non-conflicting packages work in either import order;
+- strict TypeScript sees the exact registered action methods through
+  `RegisteredExtensionActions`;
+- earlier programs and caller-owned input remain unchanged;
+- semantic and graphic state match the feature specification;
+- the trace has the intended root action and wrapped children;
+- the shortest valid call, boundary values, empty or missing input, invalid
+  input, ambiguity, repeated calls, supported lifecycle changes, and recovery
+  after failure behave explicitly;
+- semantic revisions leave no stale binding, graphic, guide, context, or
+  duplicate resource;
+- a primitive baseline and public extension program satisfy their declared
+  semantic, graphic, order, renderer-call, and representative visual parity;
+- failures are deterministic and explain how to correct invalid or ambiguous
+  input; and
+- representative rendering succeeds in every renderer the extension claims to
+  support.
+
+Keep the extension specification, implementation, declarations, package
+exports, tests, examples, and user documentation synchronized as one
+user-facing change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ggaction",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Build charts through immutable, traceable graphical actions.",
   "license": "MIT",
   "author": "Hyeon Jeon",
@@ -25,6 +25,7 @@
     "src/",
     "!src/**/AGENTS.md",
     "knowledge/action-cards.json",
+    "knowledge/extension-authoring.md",
     "knowledge/intent-taxonomy.json",
     "knowledge/mcp-resources.json",
     "knowledge/task-packet.schema.json",

package/src/core/action.js

@@ -1,5 +1,11 @@
 import { cloneAndFreeze, freezeOwned, isPlainObject } from "./immutable.js";
 
+const metadataByWrappedAction = new WeakMap();
+
+export function getWrappedActionMetadata(value) {
+  return metadataByWrappedAction.get(value);
+}
+
 function summarizeObject(value, ancestors = new WeakSet()) {
   if (ancestors.has(value)) {
     throw new TypeError("Action arguments must not contain circular references.");
@@ -107,24 +113,33 @@ export function action(metadata, implementation) {
     throw new Error(`Unknown action scope "${scope}".`);
   }
 
-  return function wrappedAction(args = {}) {
+  const ownedMetadata = freezeOwned({
+    op: metadata.op,
+    description: metadata.description,
+    scope
+  });
+
+  const wrappedAction = function wrappedAction(args = {}) {
     if (!isPlainObject(args)) {
       throw new TypeError("Action arguments must be a plain object.");
     }
 
-    if (scope === "unit") this._assertUnitProgram(metadata.op);
-    if (scope === "composition") this._assertCompositionProgram(metadata.op);
+    if (scope === "unit") this._assertUnitProgram(ownedMetadata.op);
+    if (scope === "composition") this._assertCompositionProgram(ownedMetadata.op);
 
     const entered = this._enterAction({
-      ...metadata,
+      ...ownedMetadata,
       args: summarizeArgs(args)
     });
     const result = implementation.call(entered, args);
 
     if (!(result instanceof this.constructor)) {
-      throw new TypeError(`${metadata.op} must return a ChartProgram.`);
+      throw new TypeError(`${ownedMetadata.op} must return a ChartProgram.`);
     }
 
     return result._exitAction();
   };
+
+  metadataByWrappedAction.set(wrappedAction, ownedMetadata);
+  return wrappedAction;
 }

package/src/core/extensionRegistry.js

@@ -0,0 +1,104 @@
+import { getWrappedActionMetadata } from "./action.js";
+import { isPlainObject } from "./immutable.js";
+
+const ACTION_NAME_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const DEFINITION_KEYS = new Set(["name", "actions"]);
+const registeredExtensionNames = new Set();
+
+function readDataProperty(object, key, owner) {
+  const descriptor = Object.getOwnPropertyDescriptor(object, key);
+  if (descriptor === undefined) {
+    throw new TypeError(`${owner} requires a ${key} property.`);
+  }
+  if (!("value" in descriptor)) {
+    throw new TypeError(`${owner} ${key} must be a data property.`);
+  }
+  return descriptor.value;
+}
+
+function validateDefinitionShape(definition) {
+  if (!isPlainObject(definition)) {
+    throw new TypeError("Extension definition must be a plain object.");
+  }
+
+  for (const key of Reflect.ownKeys(definition)) {
+    if (typeof key !== "string" || !DEFINITION_KEYS.has(key)) {
+      throw new TypeError(`Unknown extension definition property "${String(key)}".`);
+    }
+  }
+
+  const name = readDataProperty(definition, "name", "Extension definition");
+  const actions = readDataProperty(
+    definition,
+    "actions",
+    "Extension definition"
+  );
+
+  if (
+    typeof name !== "string" ||
+    name.length === 0 ||
+    name !== name.trim()
+  ) {
+    throw new TypeError("Extension name must be a non-empty trimmed string.");
+  }
+  if (!isPlainObject(actions)) {
+    throw new TypeError("Extension actions must be a plain object.");
+  }
+
+  return { name, actions };
+}
+
+export function registerProgramExtension(ProgramClass, definition) {
+  const { name, actions } = validateDefinitionShape(definition);
+
+  if (registeredExtensionNames.has(name)) {
+    throw new Error(`Extension "${name}" is already registered.`);
+  }
+  if (!Object.isExtensible(ProgramClass.prototype)) {
+    throw new Error("ChartProgram prototype does not accept extension actions.");
+  }
+
+  const program = new ProgramClass();
+  const descriptors = Object.create(null);
+  const actionNames = Reflect.ownKeys(actions);
+  if (actionNames.length === 0) {
+    throw new TypeError("Extension actions must contain at least one action.");
+  }
+
+  for (const actionName of actionNames) {
+    if (
+      typeof actionName !== "string" ||
+      !ACTION_NAME_PATTERN.test(actionName)
+    ) {
+      throw new TypeError(
+        `Extension action name "${String(actionName)}" must be a JavaScript identifier.`
+      );
+    }
+
+    const action = readDataProperty(actions, actionName, "Extension actions");
+    const metadata = getWrappedActionMetadata(action);
+    if (metadata === undefined) {
+      throw new TypeError(
+        `Extension action "${actionName}" must be created with action().`
+      );
+    }
+    if (metadata.op !== actionName) {
+      throw new Error(
+        `Extension action "${actionName}" must use the same action op.`
+      );
+    }
+    if (actionName in program) {
+      throw new Error(`ChartProgram action "${actionName}" is already defined.`);
+    }
+
+    descriptors[actionName] = {
+      value: action,
+      configurable: false,
+      enumerable: true,
+      writable: false
+    };
+  }
+
+  Object.defineProperties(ProgramClass.prototype, descriptors);
+  registeredExtensionNames.add(name);
+}

package/src/extension.js

@@ -1,2 +1,9 @@
 export { action } from "./core/action.js";
-export { ChartProgram } from "./ChartProgram.js";
+import { ChartProgram } from "./ChartProgram.js";
+import { registerProgramExtension } from "./core/extensionRegistry.js";
+
+export { ChartProgram };
+
+export function registerExtension(definition) {
+  registerProgramExtension(ChartProgram, definition);
+}

package/types/extension.d.ts

@@ -15,6 +15,21 @@ export interface ActionMetadata {
   scope?: "unit" | "composition" | "any";
 }
 
+export interface RegisteredExtensionActions {}
+
+export type RegisteredExtensionAction = (
+  this: ChartProgram,
+  ...args: any[]
+) => ChartProgram;
+
+export interface ExtensionDefinition<
+  TActions extends Readonly<Record<string, RegisteredExtensionAction>> =
+    Readonly<Record<string, RegisteredExtensionAction>>
+> {
+  name: string;
+  actions: TActions;
+}
+
 export function action<TOptions extends ActionOptions = ActionOptions>(
   metadata: ActionMetadata,
   implementation: (this: ChartProgram, options: TOptions) => ChartProgram
@@ -22,3 +37,7 @@ export function action<TOptions extends ActionOptions = ActionOptions>(
   this: TProgram,
   options?: TOptions
 ) => TProgram;
+
+export function registerExtension<
+  TActions extends Readonly<Record<string, RegisteredExtensionAction>>
+>(definition: ExtensionDefinition<TActions>): void;

package/types/program.d.ts

@@ -1,3 +1,5 @@
+import type { RegisteredExtensionActions } from "./extension.js";
+
 export type FieldType = "quantitative" | "temporal" | "ordinal" | "nominal";
 export type GraphicType =
   | "canvas"
@@ -2189,6 +2191,8 @@ export interface EditTitleOptions
   subtitle?: string | false;
 }
 
+export interface ChartProgram extends RegisteredExtensionActions {}
+
 export class ChartProgram {
   constructor(state?: ActionOptions);
   readonly semanticSpec: SemanticSpec;