@pathmx/completion 0.5.0 → 0.5.2

package/README.md

@@ -1,28 +1,27 @@
 # `@pathmx/completion`
 
-The opt-in, domain-neutral Completion primitive for PathMX. It owns stable
-Source-local leaf references, Actor-owned outcomes, flat summaries, State
-persistence, authored manual targets, and the canonical set/unset Action. It
-does not own Path trees, forms, or domain rollups.
+Actor-relative completion tracking for PathMX. It stores stable terminal
+outcomes while domains such as Paths and Assessment own their structure and
+rollups.
 
-```ts
-import { createCompletionPlugin } from "@pathmx/completion"
+## Install
 
-const completion = createCompletionPlugin()
+```sh
+bun run pmx plugins add completion
+```
 
-export const plugins = [completion.plugin]
+Activate Completion directly when you are not using `@pathmx/paths`:
 
-completion.reader.read(actor.id, {
-  source: "/lessons/setup.page",
-  key: "task/install",
-})
+```ts
+// plugins/completion.plugin.ts
+import { createCompletionPlugin } from "@pathmx/completion"
+
+export default createCompletionPlugin().plugin
 ```
 
-## Authored targets
+## Author completion targets
 
-A Source or authored Block can declare a manual target with the owned
-`completion` schema prop. Source targets use `source/self`; Block targets use
-their required stable authored id:
+Mark an entire Source as completable in frontmatter:
 
 ```md
 ---
@@ -30,142 +29,43 @@ completion:
   target: true
   label: Finish this lesson
 ---
-
-# Lesson
-
----
-
-<!--
-id: practice
-completion:
-  target: true
-  label: Finish the practice
-  optional: true
--->
 ```
 
-A trailing task mark produces a stable `task/<id>` target without obscuring
-the human label:
+Or add stable task targets:
 
 ```md
 - [ ] Install dependencies {#install}
 - [ ] Explore the bonus {#bonus .optional}
 ```
 
-`completionTargets(source)` projects the same frozen target model from a
-canonical `Source` or viewer-safe `SourceView`. The Completion Action is
-available only when the current Source has valid configured targets; it binds
-the Source id and validates the submitted key and optionality.
-
-Domains using Completion-owned manual facts can contribute only their stable
-keys and optionality:
-
-```ts
-const completion = createCompletionPlugin({
-  contributors: [
-    (source) =>
-      source.type === "project"
-        ? [{ key: "project/launch", optional: false }]
-        : [],
-  ],
-})
-```
-
-The domain continues to own labels, structure, and rollups. Derived evidence
-such as a valid Input submission remains owned by its provider and uses a
-separate read contract rather than writing a duplicate manual fact:
-
-```ts
-import { createCompletionPlugin } from "@pathmx/completion"
-import { createInputPlugin } from "@pathmx/core/plugins"
-
-const input = createInputPlugin()
-const completion = createCompletionPlugin({
-  evidence: [input.completion],
-})
-
-export const plugins = [input.plugin, completion.plugin]
-```
-
-Input completion is declared on one stable authored Block, making the form or
-question container—not each field—the semantic leaf:
+A Block can also declare its own target when it has a stable authored id:
 
 ```md
 <!--
-id: reflection
-input-response:
-  completion: true
+id: practice
+completion:
+  target: true
+  label: Finish the practice
 -->
-
-<x-input-text name="response" label="Reflection" required />
-<x-input-submit label="Save response" />
 ```
 
-This declares `input/reflection`. It becomes complete only when that Actor has
-a submitted Input State whose values still validate against the current
-authored fields. The derived target never exposes `completion:set` and never
-writes Completion State. Input currently owns one aggregate State per Source,
-so a Source may declare one Input completion Block.
+Run `bun run pmx lint` to catch malformed, duplicate, or stale completion
+targets.
 
-`pmx lint` reports malformed props, unstable Block targets, checked or empty
-marked tasks, invalid and duplicate keys, stale facts, manual/derived
-collisions, and invalid skips for the currently configured contributors and
-evidence providers. Input additionally reports invalid completion containers,
-bound State references, and stored values.
+## Plugin API
 
-State is grouped by originating Source and stores only terminal leaf outcomes:
+`createCompletionPlugin()` returns both a Plugin factory and an Actor-relative
+reader:
 
-```yaml
----
-type: state
-plugin: completion
-for: /lessons/setup.page
-items:
-  task/install:
-    outcome: complete
-    occurred_at: 2026-08-22T12:00:00.000Z
-  task/bonus:
-    outcome: skipped
-    occurred_at: 2026-08-22T12:05:00.000Z
----
-```
+```ts
+import { createCompletionPlugin } from "@pathmx/completion"
 
-`occurred_at` is the occurrence time of the current terminal fact. Repeating
-the same outcome preserves it; clearing and completing again records a new
-time. `pending` is represented by the absence of an item. Provider evidence is
-read through the composed Completion reader; domain rollups remain with their
-owning plugins.
-
-## React apps
-
-React remains an optional subpath:
-
-```tsx
-import {
-  CompletionProvider,
-  useCompletion,
-  useCompletionAction,
-} from "@pathmx/completion/react"
-
-function Task() {
-  const fact = useCompletion("task/install")
-  const completion = useCompletionAction("task/install")
-  return (
-    <button
-      disabled={completion.pending}
-      onClick={() => completion.set(fact ? "pending" : "complete")}
-    >
-      {fact ? "Completed" : "Mark complete"}
-    </button>
-  )
-}
-
-;<CompletionProvider initial={serverProjectedFacts}>
-  <Task />
-</CompletionProvider>
+const completion = createCompletionPlugin()
+const fact = completion.reader.read(actor.id, {
+  source: "/lessons/setup.page",
+  key: "task/install",
+})
 ```
 
-The App Component server renderer supplies `serverProjectedFacts` for the
-current viewer. The browser receives no Completion reader or repository
-access. See `labs/assessment/plugins/class-assessment` for a complete App
-Component using the same provider with derived submission completion.
+React integrations can import `CompletionProvider`, `useCompletion`, and
+`useCompletionAction` from `@pathmx/completion/react`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pathmx/completion",
   "description": "Actor-relative completion tracking for PathMX.",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",