todo

- CONSIDER: how do you address the top level scope object if it doesnt have a key?
  - youd have to keep track of where the top level scope was drawn from, for attaching listeners to things that refer to it
- CONSIDER: if you negate a failed lookup, do you want it to be truthy?

- BUG (big): for certain blocks, treat lookup failures like ifs, turning off render and display
  - anchored
  - bindItem
  - for
- BUG (overhaul): unify hide/show behavior with a reason list, and only show when all are cleared
- BUG: muti spaces in string inputs get collapsed(just use a sequential parser with two states)
- BUG: ! if two directives modify the class 'reactConditionallyHidden', they will clobber eachother
- BUG (big): if the reactConditionallyHidden css rule is listed after other more specific rules, they'll be overridden
- attrIf needs the same persistence behavior as classIf, write test for it first
- BUG (big): class() went missing
- BUG (possibly): check if this issue exists: after an if directive evaluates to false, setting it to true and activating the listener should update subtree
- BUG (someday): should skip binding scopes when looking for scope to iterate over

- MAKE SURE: using 'contain' on a jquery object with many nodes results in rendering them all

- JANKY: in createItemNodes, we simply put an observer on the length property that results in a complete re-render of the looping directive if ever a change in length is noticed

- ARCHITECTURE (consider): should we really be updating the whole branch when a with-like block changes? Possibly we should only update the things that have changed. seems like we're doing it right though, since they would all necessarily care about the change
- ARCHITECTURE: create in-js syntax for data binding
- ARCHITECTURE: binding syntax
  - allow dynamic partial inclusion
  - allow full-featured subtemplating, code sharing in templates
- ARCHITECTURE: partials
- ARCHITECTURE: an in-javascript syntax for defining bound relationships of objects and nodes
- ARCHITECTURE: provide a this token in language syntax
- ARCHITECTURE: move toward a multi-attribute language
  - move toward a DirectiveCollections for nodes, instead of sequenced lists
  - refactor .search()
  - refactor selectors
  - support precedence (anchor, with, ..., loop)
- ARCHITECTURE: rename to bound

- INTERFACE: make a way to tell bound to update a moved dom node to reflect its current scope
- INTERFACE (small): make bound() return a _$$ instance for any node-like objects
- INTERFACE: add each directive, which doesn't get an index
  - INTERFACE (repair/deprecation): phase out 'for' directive
- INTERFACE: rebrand the .update() function to mean 'sync with new dom tree context'
- INTERFACE: finish jquery syntax for finding bound subnodes
  - must filters out anchored children
- INTERFACE: also, jquery syntax for finding anchored children
  - allow them to be addressed by explicit names of some sort?
  - jquery selection syntax for finding child directives that reference properties available in the current directive's scope
- INTERFACE: allow string inputs for templates
- INTERFACE: some sort of explicitly named anchor feature? similar to the old react.name() function:
  test('can name objects', function(){
    ok(react.name('visitor', alice) === alice, 'naming a scope returns the scope');
    ok(react.scopes.visitor === alice, 'react.scopes held the specified object at the specified name');
  });
- INTERFACE: move to .commit() for updating observers

- FEATURE: make sure iteration works over jquery objects and other array-likes
- FEATURE: allow delayed updates that wait until a flag is turned on (add a readiness flag for objects)
- FEATURE: allow string inputs to directives to contain escaped quotation marks and other control characters
- FEATURE: support true and false values
- FEATURE: support numbers
- FEATURE (big): support json-like blocks with scope-chain lookup for the values
- FEATURE: provide top-level access to the global scope, and a dummy global scope

- IMPROVEMENT: mutation of loop nodes should be persistent
  - deleting a node means no update happens
  - re-ordering nodes in a loop remains the same
  - add a class to every generated node for easy lookup/modification in the tree

- REFACTOR: deprecate internal access-by-index for directiveSets - move to access-by-key with some form of sequence encoding (linked list?)
- REFACTOR: prefix probably doesn't need to be stored in scopeChain, it can be passed via potentialObservers. this would allow .observe() to be taken off the scopeChain object
- REFACTOR: deprecate .get()/.set() helpers from test suite in favor of .commit

- SAFEGUARD: whenever a directive might insert a node, verify that the node has not been rendered for a different context already during this update
- SAFEGUARD: harden all operations after run() has completed
- SAFEGUARD: in pre-lookups, restrict all keys to valid alphanumerics
- SAFEGUARD: type check in iteration, and only allow arrays (especially not strings)
  - in createItemNodes, don't allow looping over static native objects (like strings - this is almost certainly an error)

- INTERNAL FEATURE: in directive handlers, provide access to the tokens that lead to each input, as well as the values. should help with things like iteration directives, that needed keys for their generated scope chains or child node directives
- INTERNAL FEATURE: directive handlers should be run in the context of a node
- INTERNAL FEATURE: monitoring support for run operations
  - how many nodes were visted
  - how many directives were processed
  - if directives were ever re-visted
- INTERNAL FEATURE: provide every directive with a .persistence() helper, that can access a shared state based on previous executions of that same directive. Useful for unsetting previously defined classes and attributes, and allows those functions to be auto-resolved

- MEMORY (loose end): *disassociate listeners when node gets updated against new object
  - clean up any pre-existing observers (lookup time? observation time?)
- MEMORY: store observers on a per-anchoring basis, for easy cleanup of memory references

- PERFORMANCE: cache scopeChain objects between operations, invalidate only as necessary
- PERFORMANCE (possibly): when selecting react nodes to visit, generate a :not() selector that excludes children of other react nodes. some say its crazy slow? works in all but IE<=8 (http://www.quirksmode.org/css/contents.html), and is no slower there (since we have to visit all nodes anyway). have to check that selection behavior is same as jquery though, and doesn't consider parents of the selection context.
- PERFORMANCE: for compressability, rework error messages to be shorter and described more fully in comments

- FUTURE: build documentation app
- FUTURE: write a publish script that updates versions correctly, generates a new distribution version, runs all tests, concatenates together any relevant pieces
- FUTURE: build an app framework on top
- FUTURE: build the animation system
- FUTURE: investigate building a node project that runs this bound on the server and hands over the rendered html
  - would it pass state along too, and how?
  - how would the client boot all this info?
- FUTURE: move away from jquery dependency
  - change $.find() back to queryselectorall $.find() (note calling Array.prototype.slice.call on the results of a call to .querySelectorAll blows up in IE)
    - see if there's a more efficient way to build an array of these objects, other than iterating over the array like object

- DOCS: update readme
- DOCS: add proper interface docs
- DOCS: do a comment sweep

- RELIABILITY: write tests for js.js
- RELIABILITY: write tests for bound.proxy
- RELIABILIITY: build performance tests


--- tests ---
- tests around assumptions for template modification
  - moving a subtree within the structure makes it stop behaving in a bound fashion
    - and disassociates the listeners?
- test iteration count to ensure this behavior is working: earmark any nodes that have been found in a querySelectorAll call, so we don't have to add their children again when they show up in the 'branchesToConsider' list
- negation doesnt break for dot access
- classIf is not cumulative. the second time a class is added, the old one will not be cleaned up
- test that when a directive has already had all subtrees queued for visiting, visitBranch() passes for repeat calls
- without using .data(), IE copies expando properties over, breaking loop behaviors and other cloning operations. write a test for the failing behavior and implement replacement to .data()
- test that integrate.jQuery.items() works, as well as .itemTemplate(). also, error when called on non-looping nodes
- second descendants of a deadDescendants branch and a dirtyDescendants branch should inherit the state
- when a directive is marked for consideration, then removed from the tree by a contain or withinEach directive, the node still works if another directive swapps it in. probably doesnt matter since substituted nodes don't get recursed onto
- empty react attribute string doesnt break universe
- attributes should be removed if property is undefined, even after deletion
- when a within command fails lookup, the new scope is not added to the chain
- cannot pass jquery objects to react.update() that have more than 1 element
- test that every directive can be run on an undefined object
- 'anchored', 'within', 'withinItem', and 'bindItem' all need their subtrees rerendered on change
- nodes within a contain directive don't inherit a scope chain
- ideally, lookups dont fall through above a contain or anchored directive
- updates to properties that had been listened to with bindItem might not recalculate (since they're listening to the wrong scope object). maybe this just applies when the name being bound to changes
- within can be run on undefined objects (should this turn the branch off like 'if', or just not add the scope to the chain?)
- can anchor one node to multiple scopes
- verify that responses to change events don't result in new observers
- can use dot access on bound items
- updates to items in a list (associated with the key or value of a bindItem) change appropriately. consider listener.check(), which might not have updated unless the fallthrough registration just worked
- test support for anchoring to whole scope chains
- test('increasing the length property of a list appends extra nodes', function(){});
- test('reducing the length property of a list deletes extra nodes', function(){});
- test('lookups to loop items don\'t fall through past the top scope if that item holds undefined', function(){});
- test('don\'t allow looping within non-enumerable (or non-observable) objects', function(){});
- test('recomputes all subnodes when changing the value stored at some index of an observed array that was looped over', function(){});
- test('when a list item is removed, associated loop item nodes disappear', function(){
- test('todo: write a test this for inadvertent fallthrough, for the case where lookup of a withinItem key hits undefined and falls through this._lookupInScopeChain(args[0], lastLink)', function(){});
- test('works with a missing key alias', function(){/*...*/});
- modifying the directives attribute after initializing a node throws an error on next visit to the node
/* todo
  var object = ['a', 'b'];
  var node = $('\
    <div react="for which item">\
      <span class="item" react="contain item"></span>\
    <span id="container"></span></div>\
  ')[0];
  react.update({node: node, scope: object, anchor: true});
  same($($('#container .item', node)[1]).html(), 'b', 'second item got set');
  object.slice(0,1);
  react.changed(object, 1);
  // before the bug fix, the binding instruction from the outer 'for' directive never got blown away as the scope chain got built up
  // thus, there would have been an extra key binding scope, instead of the normal withinEach style scope change into a property
  same($('#container .item', node).length, 1, 'redundant node got deleted');
*/
});